Thought Share - How to write a useful design document

How to write design document? Are you kidding? After all we have had many years experience in design document.



These days I have done some design work for Automatic Claim Handling and Letter.

I reviewed previous design documents and kept thinking what should be putted into the document and what should not.

Actually, I am not alone in this issue. In software community, it’s always a hot controversial topic. Extremely there are two distinct voices.



1. CMM advocators insist on tons of documents including comprehensive design document

2. Some Agile advocators speak out design document is useless and design is dead



Eventually, I find myself at the center of this argument. I am not 空头, I am not 多头，I want to be “滑头”, I always want to be pragmatic.

So what’s a design document for?

Basically it acts as a bridge between business solution and code implementation. Dose the document stuff really help it?

Where the answer is yes, I intend to move forward, where the answer is no, action will end.



Let’s have a look at the advantage and disadvantage of design document.



Advantage:

1. It’s good at describe the whole architecture in high level and lead in a right direction

2. It’s vivid and expressive with many diagram, notation and easy to communicate

3. In interface design, it can be a deliverable contract with outer system



Disadvantage:

1. It’s incline to be out of date

First, it's hard to think through all the issues that you need to deal with when you are programming.

Even we can carry it out with extra effort, it’s impossible even for the most experienced designer to foresee requirement change.

2. It’s hard to verify automatically comparing with unit test

Although UML diagram and notation can decrease the ambiguous, it’s still mainly for human-beings. Document is hard to be synchronized with the implementation.



So my principle is to adopt the strength and avoid the weakness.

1. It can never be too detailed for interface contract design document

2. Design document should clarify the boundary with outer system

3. Design document should express high level concern and main point of business solution

4. Design document should setup common convention and pattern.

5. Design document should not run into implementation detail.

6. Unit test should be involved to help to reflect requirement and design.



Remember, it is better to have few useful design documents that you use and keep up to date than to have many forgotten, obsolete documents.