Documentation

I was going through the design documentation of our project: It started out 2+ years ago with a requirements document (following the IEEE-830-1998 standard) from which we created an architectural design document (following the IEEE-1016-1998 standard) which we broke up into detailed design documents, one for each component of the system. I think we can truthfully claim that the first version of our product was fully compliant with the high-level documents. But in the following bug and minor releases not all high-level documents got updated, and now we are at our third minor release and the documents have become seriously out of synch. Maintaining the original documents is a headache and now the only time you will find me reading them is when I am checking on how outdated they have become, never to refresh myself on some high-level detail. Hmmmm.... So I started to rethink (as no doubt many before me) what the purpose with these high-level documents is, and the remainder of this entry is meant to ponder that question.

Requirements
With regards to the requirements documentation, I think that at the start of a project it is helpful to have a requirements document, the IEEE standard one is good to follow so that that no details get left out. It is useful to have one complete document to keep an overview of the functionality of the whole system. It is also a good medium for circulating the requirements within a reviewers group. However, when the development is under way, I think that the requirements document should be phased out (not maintained) with an issue management tool. The old requirements do not necessarily need to be transferred to the issue management tool, but all new requirements should be entered into it. Using an issue management tool makes project and release managements much easier: each issue gets a priority and a designated developer, and a log of its history (changes and comments) is maintained. And when it is time to do a new release it is easy to determine the current status of the software, what has changed since the last release and what has been left out as open issues.

Code Design
I think that it is necessary to keep the code as readable (self-documenting) as possible. It is necessary to include documentation for the following items. This might be best done within a #region of the code or perhaps in a separate document that is placed close to the code, convenience dictating the choice:

• Scope: What this component is to do and what not (I am assuming a component based design)
  
• Design: What high-level structure (pattern) was selected to solve the business problem
• Design alternatives: What other structures were considered
• Design rational: Why the design alternatives were rejected and the selected design chosen

The reason why these items should be documented is to facilitate the next developer to know the thinking of the original author (be it himself re-acquainting himself with the code some years later or a completely new developer).

What should not be documented:

• Class diagrams, since they can be automatically generated, if needed (using Visio e.g.)
• Database diagrams, since they can be automatically generated, if needed (using Management Studio e.g.)

In general, the documentation should be kept as sparse as possible, in the spirit of YAGNI and KISS.