What are the best practice for writing detailed design documents?

Question

Please suggest material regarding the best practices for writing design documents.

Answer 1

This article on Writing Quality Requirements would probably be worth the read. The end of the article has some general "Guidelines" that would probably be useful to you.

Among the guidelines are things like:

• Keep sentences and paragraphs short
• Use the active voice
• Find the right level of granularity (requirements written should be individually testable)
• Avoid writing multiple requirements in a single statement (conjunctions like "and" and "or" can help you spot this)

Lots of other good resources similar to the above article are available to help give you some perspective. If you're looking for a much more comprehensive look at requirements "best practices", check out Software Requirements, Second Edition (Amazon).

Answer 2

I also have to recommend not only the book that Donut suggested in his last sentence, Software Requirements (2nd Edition), but also a companion to that book - More About Software Requirements. Both books are by Karl Wiegers, and his website has some interesting reading as well, in particular the Goodies section, which has freeware sample documents and templates.

Answer 3

Just some basic thoughts:

• know the audience that you're writing for and adjust as needed (remember you need to get the message/information across effectively)
• top down, make the design into an understandable story
• only put as much detail as needed - there will always be questions about the spec, don't over work it and be open to changes
• keep a version and change log section in the spec so people know what the latest is and what was changed
• take a look at mindmapping for gathering your thoughts prior to writing