How-to article
Explain step by step how to do one task.
Propose a technical design and get it reviewed before you build it.
Author | @mention the author |
Reviewers | @mention the reviewers |
Status | ⚪ Draft | 🟡 In review | 🟢 Approved | 🔴 Rejected |
Last updated |
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
🚫 Non-goals
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.
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 |
The risks of the design, and how you reduce each one.
The questions that are still open, and who will answer each one.
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.
Reviewer | Decision | Date |
|---|---|---|
@mention the reviewer | 🟢 Approved | 🟡 Changes needed |