Document During Development
Finally we introduce the documentation. Having outlined the Business Rules and decided on the Features we need to add or update in the system to accommodate these rules, we then decide what components will be affected. We may add, update or even remove components to meet the requirements for each Feature.
During the Design phase, we select the components we will need to change. The Design documentation for these changes is recorded for each component for each feature. This also allows us to be far more accurate in the estimation of the effort required for each Feature. Once this is complete, and it is typically a joint effort between developers that may have several iterations, the estimated effort can be refined and finalized.
During the Development phase, these Design notes act as a reference as to the changes that need to be made. Since most systems are of varying complexity, there are often additional changes needing to be made. These are added appropriately, and the changes to the original Design are then clear and justified.
Finally, the code will be reviewed. Typically we have found that reviewing code can be a difficult process. When one deals with plain textual code, the changes are somewhat easier to determine by use of a file comparison tool. When we are using more sophisticated software, where most changes may be made to properties of components rather than writing code, the changes are far more difficult to determine.
Generally reviews require explanations from the developer, and more often than not, details can be skipped over or even unintentionally ignored. This is fatal for a proper review.
With the addition of specific documentation for every change made to every component to support a Feature, we remove much of the ambiguity of the review process. As developers get used to the needs of the reviewer, it becomes second nature to provide the required documentation for a reviewer to be sure what changes have been made. As we generally rely on both peer and supervisor reviews, most developers learn very quickly what makes for an easy review, and what does not.
Although the immediate intention is to enable a successful and easy review process, the long term benefits of this are huge. Effectively we have ensured that the intentions and the activities of each developer are recorded in a way that is easy to understand. As each change can be related to either the Component changed, or the Feature added to the system, the eventual documentation becomes full and detailed reference documentation, with no additional effort outside of the development process itself.