"Lots of documents do not make good documentation."
Daniel Freedman
Major design documents:
This should provide enough information for a reader to understand the rest of the documents. This is the first document a new team member should read.
Define any new or unusual terms which are used in the rest of the product documentation. Be especially careful to flag any standard terms which are being used in an unusual way. If there aren't that many new terms, this may be part of the overview.
"Why write specs if we already have code?" This is a good question that's often asked by developers. In an area where the number of solutions that meet requirements is very small, the Product Requirements and the product itself may be enough information to test against. Where there are a large number of possible solutions, this is not the case.
Testing needs to know what solution development has in mind. Functional specifications should document "intent". Testers can't verify functionality if they don't know the intent. They should be able to tell from the functional specification whether any observed behavior is a bug or a feature.
Another important type of information for the functional specification is any place in the product where obvious assumptions will be wrong. For instance, most testers would assume that a button marked "Run" and a menu item "Run" that did the same thing would go through the same code. If this is not true, it needs to be documented.
The code is the record of how the product acutally behaves, but cannot indicate if that is how the product should behave. Intent should be documented in the functional specification. From development's point of view, engineers can't find design holes if they don't know what each developer intends to do. The project is done when the code matches the intent.
A design specification provides implementation details for other developers. This should document design decisions and rationales for future reference. These can be a big win for maintenance. Chances are good that if designs are not well documented up front, they never will be.
Comments can indicate the intention of the code, but often address intention at too low a level. Comments usually provide details about why a specific code block exists, but seldom do more than hint at overall structure. Gleaning high level design concepts by reading code is not a good use of testing time. Some would go so far as to argue that being too close to the code tends to prevent people from seeing high level issues.
Copyright 1998 Anne Powell