Remember: Write for the human brain, not the compiler.
When you write code, you write for the compiler, which can understand that you start at the top and work your way to the bottom with full details. But the human brain functions differently. A human brain understands things better if you give it the story of the code. While writing for humans, start the story with the primary use case, then build up to the big picture, show them the workflow, then introduce the areas of impact. At this point, you may include high-level code implementation details. And end the story with the future scope for the feature. In summary:
|Objective||In case of a new feature, mention the overview of the feature in terms of requirements. In case of a bug fix, mention the Problem Statement.|
|Big Picture/Context View||Describe how the feature fits in the existing architecture.|
|Background and prerequisites||Describe the concepts and theory that the reader must know to understand the objective and the solution.|
|Possible solutions||List and analyze the possible solutions that can be implemented to achieve our objective.|
|Solution||Describe the chosen solution and give the rationale behind the choice.|
|Workflow||Describe how the solution works.|
|Areas of impact||List the components and modules that are affected by the chosen solution. Describe the impact and workarounds, if any.|
|Code implementation||Give a high-level overview of the code implementation.|
|Scenarios not addressed||Describe the scenarios or use cases that are not addressed by the solution.|
|Future work||Describe the future scope for the feature, if applicable.|
Design docs are usually written as an after-thought. This practice can make writing design docs seem like a mammoth task that you are forced to do. Instead of writing it at the end in one shot, you can write it in chunks by following the Feature Calendar:
|Feature Calendar Milestone||Section of design doc corresponding to the milestone|
|Team discussion meeting||High-level requirements
Big picture view
|Engineering requirements meeting||Functional specifications
|Design review meeting||Proposed design
Areas of impact
Workarounds: How are we going to handle the impact
Scenarios not addressed
Tips and tricks:
The design doc is not the English translation for the code, it complements the code
The design doc should include all the information that cannot be understood from browsing the code, and no more. It should be a preface to the code.
Write in a conversational tone
While writing design docs, we tend to use formal language and technical jargon. Instead, use a conversational tone and write as if you are explaining the design to someone in person. It would make the reader’s life much easier.
Know your audience
Choose the sections to be included in the design doc depending on your audience. For instance, if the QA team is the audience, you might want to add a section on what are the at-risk aspects of the design, so they can focus on testing it. Or if the UI team is the intended audience, you can elaborate on the requirements from the UI perspective.