[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.