Andrew Channels Dexter Pinion

Wherein I write some stuff that you may like to read. Or not, its up to you really.

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;

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