cloudstack-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ron Wheeler <>
Subject A good article on developing large systems
Date Thu, 03 Aug 2017 19:37:16 GMT 
has on page 7:

"The philosophy behind DocumentationDriven API Design or Development is 
simple: from the perspective of a user, if a feature is not documented, 
then it does not exist, and if a feature is documented incorrectly, then 
it is broken."


You can do this as you design an API, or later if you’d like to rework 
an existing API. Wherever the documentation becomes complicated or 
difficult to write, revisit the design. This process works because it is 
easier to spot complexity in the documentation than in the code.
Figure out how you are going to describe the feature to users; if it is 
not documented, it does not exist.

Whenever possible, documentation should be reviewed by users before any 
development begins. This also gives you the chance to get your ideas 
peer-reviewed, since it helps users to understand what you are trying to do.

Once documentation has been written, development should commence, 
preferably test-driven development. Both developers and testers can 
start working on the implementation, one focusing on writing code and 
the other on writing automatic tests.

Unit tests should be written to test the features as described in the 
documentation. If the functionality is ever out of alignment with the 
documentation, tests should fail.

When a feature is being modified, it should be modified 
documentation-first; when documentation is modified, so should the tests 
change. Along with the tests being changed, the coding will also have to 
be modified accordingly.

Documentation and software should both be versioned, and the versions 
should match so someone working with old versions of software will be 
able to find the proper documentation."

This would seem to make evaluating PRs a lot easier. 3 sets of PRs would 
be have to approved but the approval of each one would be much easier 
and involve a lot less risk.
We would also have much better documentation, much clearer Release Notes 
and full coverage of the test suite.

It would also expand the community by increasing the visibility of 
enhancement project and giving more opportunities for people to get 
involved in testing and coding of enhancements. People who might not 
feel comfortable developing the code might be quite willing to take on 
testing if they wanted to help gt a new feature implemented.


Ron Wheeler
Artifact Software Inc
skype: ronaldmwheeler
phone: 866-970-2435, ext 102

View raw message