A while back Greg wrote a great article about the “Rules of Design Documentation” http://etherealmind.com/rules-design-documentation-etherealmind/ these are really valuable rules when it comes to writing a design document and in my opinion is particularly relevant to a Low Level Design AKA Detailed Design Document.
Before you can apply these rules of design you must first consider the following questions:
- What is this purpose of the document ?
- What is the next step after this document ?
In fact†these questions can be asked about any document you need to produce in your career!
My Own Designs
I have produced my fair share of design document over the years and I decided to look back at some and ask the questions above. What I have found that in the introductions I don’t really state the purpose of the document very well. A typical example might be.
“This document†describes the detailed LAN design for site X and how it is connected to the WAN”
How lame is that !!!!!!
Now if I ask the questions above, then my opening gambit might have been more like:
“This documents†purpose†is to detail the design elements which make up the new LAN for site X and how the site will connect to the WAN. The design elements will break down into:
- Physical Connectivity Component and Devices
- The Layer 1 and 2 Topology
- The Layer 3 Logical topology
- The Layer 3 routing
The contents of this document will provide the “relevant” information to implement the design.”
From this I have set out a basic document structure and clearly defined what it will be used for.
Who will use it ?
Another thing that struck me recently after having designs past onto me for implementation and also looking back at my own designs. Could someone (not the designer) take the document and implement it with ease. Whether subconscious or not,††I have found that some of the necessary details get left in the designers head, therefore:
- designer + design = implementation with ease and short time frame.
- implementer + design = implementation possible but extended time frame + potentially significant interaction required with the designer to clarify points.
So when you are the designer, you must remember that the†implementer†will not have all the minor details that might be floating around your head, so make a conscious effort to consider the person who will picking up the document and have to implement it; try and get all the minor details into the design.
When writing design documents, especially detailed designs, consider the purpose of the document and state it clearly. More importantly consider the person who is going to have to implement it. With these thoughts running through your mind during the documents creation process then the receiver of the design document should have a better chance of implementing it, in a shorter time frame, with less interaction†required†with the designer.
Other posts in the series
- Low Level Design - Think about the next step (This post)
- A Better Technique for Blogging and Writing - Markdown
- EtherealMinds Eleven Rules of Design Documentation