What Makes a Good Design Document?

dnnrly asks: "I've been writing software professionaly for a couple of years now for more than 1 company and I've noticed a recurring pattern: I get put on a new project that already has a bit of history and I get told to read the design documents and then implement XYZ. What happens is I read the document, find that it gives me a lot of information about certain aspects of the system we are building, but leaves huge gaps in others. We're going to be rewriting some of the procedures very soon and I'll be able to influence the software side so I wanted to ask Slashdot readers what sort of things have they seen in design documents that they've liked/thought are a good idea? What have they found works and what doesn't? If all else fails, where's a good place to find all this stuff out?" "There's usually a very defined and rigid format for every design document and the writers have obviously tried very hard to make sure that procedure has been followed, generally leading to an almost unreadable doc or a design for the sake of it. Part of the issue is that these guys have written the design after 2 or more years exposure to the problem so they tend to forget just how much they know."

Comments

Re:I hate it when that happens

[Grab]

Good call.

Pseudo-code, or any other formal or semi-formal tool, is the kiss of death. Do not EVER, under ANY circumstances, use ANY method to document exactly what the code should do. It is always quicker to just write the damn code, and your design document becomes an unusable pile of crap.

What a design document should say is what they want the design to do, and the decisions made in implementing it. So the architecture, the interface between your software and the outside world, and the interfaces between chunks of your software are essential to capture. Data flow diagrams are a useful tool here. A truly vast amount of errors come from interface issues, where group A expected one thing and group B expected another. NASA's little oopsie in units is a good example, but another thing to beware of is deadlock, where process A is waiting for message X before it sends message Y, and process B is waiting for message Y before it sends message X.

Flow charts and state machines can be useful, but only as a method of documenting what's supposed to be happening in the "big picture". A good guideline is that if you ever find yourself using variable names, this is the point to close down your current diagram, delete it, and probably delete the next diagram or two above it as well.

What else? Hmm. "Why did you implement something a particular way?" "Oh, because it saved 200KB and 5% execution time, so it's super-efficient even though the code looks way confusing." Write it down, otherwise someone else may misunderstand your code, rewrite it and add 200KB and 5% execution time to a future release.

And if you don't have a requirements document, write your requirements in the design document. It's more of the "why did we do that?" decisions, and it also stops you getting reamed by the customer when someone realises they forgot feature X and then lies through their teeth to say they told you to do it.

Grab.