April 19, 2005
Design Documents
Well, frankly I'm shocked. Here is a cogent, well written comment posted to a Slashdot article. The original question was "what makes a good design document?" and this response says, in part, that it is;
- A statement of the problem - What are we trying to solve
- The solution to the problem - How we are going to solve the problem.
- A discussion of how the solution addresses the problem - Why we've done what we have done.
When I'm writing or reviewing documents that accompany a system I always focus on the What, How and Why of the solution. Especially important is the Why section, especially when a system is in maintenance or enhancement mode because often a first reaction when returning to work we've done previously is to ask "why was it done that way?". Except usually the language is more anglo-saxon in origin.
The other sage advice is to limit your How section to the publicly available parts. There's no need to list every line of code in a program and comment it, as I've seen done a few times. What should be included here is the information that helps you to understand the program, if you need to know exactly how it works look at the source code.
Posted by Andy Todd at April 19, 2005 08:28 AM