After working for some time (10 years +) in the software development, I found it hard to kept good documentation about the software being wrote. In the company where I work we put in place a simple documentation iteration. The iteration has implication over all the layers of development, from customers to developers, SQA, software designer, etc..
Iteration #1 - User storiesIn this iteration, we document what the customer need in the software. This part is very important, and it must be very clear for both parties. Usually, it must be verified by one of the senior programmer. When both parties agree on the user stories, it should not change afterwards (unless there some problems or better way to solve some of the user stories), this is more or less the contract between you (the company) and the customer.
Iteration #2 - FDS - Functional Design SpecificationIn this iteration, we design the UI (if needed) with all the error messages, the flow of data, the user interaction, the component interaction and architecture, the valid parameters, the input/output. In short, anything that the user will see or use, and anything that will help the user to use and comprehend the software. All this are based on iteration #1 - User Stories. When something wrong (or good (by example a better way to process data)) is found at this point, it is important to notify the customer for modifying some of the user stories (this should not happen often, something the process to make change in the user stories can be long).
Some of the acceptances tests can be defined at this point (see #7 and #8 - Acceptances tests).
Iteration #3 - DDS - Detailed Design SpecificationIn this iteration, we design the structure of the code, the classes (or modules) to be created, the sequence diagrams, anything that will help the developers. The DDS is based on the FDS. Like the FDS, if there something that may change the FDS is found in the DDS, then the FDS must be changed, and hopefully without changing the user stories.
Iteration #4 - CodeIn this iteration, we code :-) based on the DDS. The code should reflect the DDS, for example, if in the DDS there is some reference to a module called Orange, then in the code this module should be named Orange and not Banana. It should be easy to navigate in the code after reading the DDS. The DDS come handy in the future (1 year later for example) for reference about the code which may be forgotten by the developers.
Iteration #5 - Unit testsThe unit tests validate the code done in #4 - Code. These are simple tests done at the class level. Usage of mock object is the norm.
Iteration #6 - Integration testsThese tests are more complicated tests, they test the interaction between the classes, or between the components. They validate the DDS.
Iteration #7 and #8 - Acceptance testsThese tests are using the software created, in a controlled environment. They are using real data. They validate the FDS (so all the UI interactions, the result for each operation, etc.). Sometime these tests are explained in a SDT - Software Development Tests document. It can be useful for the SQA teams to help them design their own tests.
There is also customer testing but it is not something that you can document. Unless the customer is very friendly with your company.
Software Documentation Iteration Diagram
For each iteration there is a BIG arrow and a small arrow; if each iteration is done properly and professionally then the small arrow is used less. Using the small arrow is time consuming and must be avoided if possible.
The double arrows represent the relationship between the test part and the documentation part.
François
