https://dzone.com/storage/assets/6002108-dzone-guidetointegration-volumeiv.pdf
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."
also
DOCUMENT YOUR API OR FEATURE FIRST
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.
DO DOCUMENTATION REVIEWS
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.
WORK IN PARALLEL
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.
TESTING
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.
CHANGES
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.
VERSIONING
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
--
Ron Wheeler
President
Artifact Software Inc
email: rwhee...@artifact-software.com
skype: ronaldmwheeler
phone: 866-970-2435, ext 102
