I came across a great article recently by Scott Hackett:  http://blog.slickedit.com/2007/05/how-to-write-an-effective-design-document/. It’s a thorough look at the reasons to write Design Documents (dd) and though it’s a few years old now, it covers one of the really important aspects of writing dd’s – What’s a good design?  Here’s a great excerpt:

“A design will typically be considered good if it fulfills the requirements in a meaningful way. If any aspect of the design cannot be justified, then it is probably worth reevaluating. Many programmers try to incorporate design patterns into their work, and they often add unnecessary complexity. You should be able to list at least one compelling reason, related to the requirements, for why a design decision was made. That reason must then be documented. If you can’t come up with a clear reason for a design decision, then it is probably not adding value.”

(Scott Hackett:2007)

This is really important and it’s usually why I start most dd’s with some sort of problem definition (ie. What are we trying to solve? or even what are we trying to build?). If you can at least point your design to that – you are at least focussing your design/solution firmly on fixing a problem. That’s a good start.

“You should be able to list at least one compelling reason, related to the requirements, for why a design decision was made.”

(Scott Hackett:2007)

I also really like the the breakdown that Scott uses for his dd’s. It is a nice clear separation of areas that can be covered in a dd:

Section 1 – State the purpose of your project/sub-system

Section 2 – Define the high level entities in your design: High level entities are objects, or groups of objects, that constitute major constructs of your design. Good examples of entities are a data access layer, a controller object, a set of business objects, etc… 

Section 3 – For each entity, define the low level design: This section is where your objects and object relationships are defined… 

Section 4 – Benefits, assumptions, risks/issues: …”

This breakdown is excellent – it’s not exactly how I split up the dd but it’s logical and it covers a wide range of issues that come up when designing something in Software Engineering.

The last section is really important. It’s a section that you as the developer will not always know at the start. You might actually think “Hey that’s a project managers job”.  I’ll cover that in the next article.