How to write a good software design doc

Refer to: 
https://medium.freecodecamp.org/how-to-write-a-good-software-design-document-66fcf019569c

Notes:

Why?

make sure the right work gets done.
1.think through the design
2.gather feedback from others

What to Include in a design doc?

1. Title and People

the author(s), the reviewer(s), the date the document was last updated.

2. Overview 

• A high level summary 
• 3 paragraphs max

3. Goals and Non-Goals 

• describe the user-driven impact of your project 
• specify how to measure success using metrics (bonus points if you can link to a dashboard that tracks those metrics)

4. Milestones

• listing out important milestones, but not yet attaching them to specific dates 

5. Current Solution  

• A user story is a great way to frame this.
• current implementation
• how users interact with this system
• how data flow through it

6. Proposed Solution / Technical Architecture

7. Alternative Solutions

8. Monitoring and Alerting

9. Current Solution 

10. Cross-Team Impact

11. Discussion

12. Detailed Scoping and Timeline



How to Write it?

1. Write as simply as possible

• Simple words
• Short sentences
• Bulleted lists and/or numbered lists
• Concrete examples, like “User Alice connects her bank account, then …”

2. Add lots of charts and diagrams

3. Include numbers


Process?

1. Ask an experienced engineer or tech lead on your team to be your reviewer. 

2. Go into a conference room with a whiteboard.

3. Describe the problem that you are tackling to this engineer 

4. Then explain the implementation you have in mind, and convince them this is the right thing to build.


Doing all of this before you even start writing your design doc lets you get feedback as soon as possible, before you invest more time and get attached to any specific solution.

Then, after you’ve written a rough draft of your design doc, get the same reviewer to read through it again, and rubber stamp it by adding their name as the reviewer in the Title and People section of the design doc. 

1. You spend 5 days writing the design doc, this forces you to think through different parts of the technical architecture
2. You get feedback from reviewers that X is the riskiest part of the proposed architecture
3. You decide to implement X first to de-risk the project
4. 3 days later, you figure out that X is either not possible, or far more difficult than you originally intended
5. You decide to stop working on this project and prioritize other work instead

template:

http://ant.comm.ccu.edu.tw/course/97_Programming/7_SampleCode/Design%20Document%20Template%20-%20Chapters.pdf