[Project name] Design Doc
About this doc
Metadata about this document. Describe the scope and current status.
This doc describes the technical approach, milestones, and work planned for the [Project name linked to Product Requirements Doc]
| Sign off deadline | Date |
| Status | Draft |
| Author(s) | Name 1, Name 2 |
Sign offs
-
Name 1
-
Name 2
-
Add your name here to sign off
Context
A sentence or two on the “what.” What is being built.
Then include the “why” (metrics we intend for). Link off to Product Requirements Doc for details.
Non-goals
What is out of scope for this project that we don’t want to focus on?
-
Out of scope detail 1
-
Out of scope detail 2
-
…
Terminology
Define any new terms that are used in the document.
High level approach
Explain the technical approach in a few sentences so the reader understands the system flow
Alternatives considered
Bullet points of alternative approaches considered and why you’re not going with them.
-
Alternative 1
-
Alternative 2
-
…
Detailed design
APIs, DB tables modified, Data models changed, and any diagrams that would help the reader understand at a high level
Risks
What can go wrong with the proposed approach? How are you mitigating that?
-
Risk 1
-
Risk 2
-
…
Test plan
How will your approach be tested? Browser testing? Manual testing? Will anything be tricky to test? Adding information here also makes it easier to make a case for a longer timeline.
Milestones
How will the work be divided into chunks of progress?
Focus on the user milestones rather than technical ones. For example, having a minimal working feature behind a feature flag initially.
I usually add an additional 1 week per 2 weeks of expected feature work.
-
Milestone 1: Date 1
-
Milestone 2: Date 2
-
…
-
Rough ETA of project finish date: …
-
Project retro: …
Rollout plan
[optional] How will you gradually ramp up usage of the feature for safety?
A feature flag starting at 1% of users? Only testing in a specific region? What feature flags?
Open Questions
Anything still being figured out that you could use some additional eyes or thoughts on.
Parties involved
Who is working on this? Are there any external teams that need to sign off on this as well?
-
Eng 1: [Name]
-
Eng 2: [Name]
-
PM: [Name]
-
Designer: [Name]
-
[External team name]
Appendix
Add any detailed figures you didn’t want to inline for space.