Refer to:
https://medium.freecodecamp.org/how-to-write-a-good-software-design-document-66fcf019569c
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
3. Goals and Non-Goals
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
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.
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 …”
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.
- You spend 5 days writing the design doc, this forces you to think through different parts of the technical architecture
- You get feedback from reviewers that
Xis the riskiest part of the proposed architecture - You decide to implement
Xfirst to de-risk the project - 3 days later, you figure out that
Xis either not possible, or far more difficult than you originally intended - 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
留言
張貼留言