Design doc

Propose a technical design and get it reviewed before you build it.

Engineering


Author

@mention the author

Reviewers

@mention the reviewers

Status

⚪ Draft | 🟡 In review | 🟢 Approved | 🔴 Rejected

Last updated

Context

Two or three sentences: the problem that this design solves, and why you must solve it now.

What exists today: the systems, the limits and the facts that a reviewer must know. Link to related designs.

Goals and non-goals

🎯 Goals

  • What the design must achieve, as a result that someone can check

🚫 Non-goals

  • What the design does not try to do, so that reviewers do not ask for it

Proposed design

How the design works, from the top down: the main parts, what each part does and how they connect. Add a diagram if it helps.

The details that reviewers check: the data you store, the interfaces that change, security, performance and cost.

Alternatives considered

Option

Pros

Cons

Another way to solve the problem. Include "do nothing".

What this option does better than the proposed design

Why you did not choose it

Risks and open questions

The risks of the design, and how you reduce each one.

The questions that are still open, and who will answer each one.

Rollout plan

How you release the change: for example, in steps, behind a feature flag or to a small group of users first.

How you know that it works, and how you undo it if it does not.

Approvals

Reviewer

Decision

Date

@mention the reviewer

🟢 Approved | 🟡 Changes needed

allanswered knowledge management