Write a Design Doc
A design doc exists to be criticised before code exists. If a reviewer cannot find the weak point, the doc is hiding it, not resolving it.
Procedure
- Open with the problem and the constraints, in numbers: current latency, volume, budget, deadline. No solution in the first paragraph.
- State the goals and, explicitly, the non-goals under a
## Non-goals heading. "This does not handle multi-region" prevents scope arguments later.
- Present two or three real options, each with cost, complexity, and what it forecloses. A one-option doc is a decision already made.
- Recommend one and say why in terms of the constraints, not taste.
- Describe the proposed design with a diagram (text or ASCII), the data model, and the request path.
- List the failure modes and how the design handles each: what happens at 10x load, when a dependency is down.
- Call out the risks and the reversible decisions; mark the one-way doors.
- Give the migration and rollout plan, including rollback.
- Add an open-questions section with owners, so unresolved items are visible, not implied.
- Estimate the cost and the operational burden (on-call, new dependency, runbooks to write).
- Cap it at a few pages; link deep detail to appendices.
- Circulate for async comment before review; the doc that gets no comments is either trivial or unread.
Pitfalls
- A doc that opens with the solution, so options and tradeoffs read as rationalisation.
- Options listed but none costed, so the comparison is theatre.
- No non-goals, inviting scope creep in review.
- Diagrams that omit the failure path, showing only the happy request.
- Silently burying the risky choice instead of flagging it as a one-way door.
- A design that ignores the migration of existing data, treating greenfield as the only case.
- Estimating effort in days without a range or the assumptions behind it.
Verification
wc -l design.md && grep -cE '^#{1,3} (Non-goals|Options|Risks|Rollback)' design.md
The doc has explicit Non-goals, Options, Risks and Rollback sections. Ask a reviewer to name the design's weakest point; if they cannot from the doc alone, add the tradeoff you left implicit.
1---2name: write-a-design-doc3description: Use when proposing a non-trivial system change that needs review before build. Frames the problem, options with costs, the chosen design, and the risks, for a reviewer to attack.4metadata:5 source: https://skillmd.com/skills/jiayaoqijia/write-a-design-doc6---78# Write a Design Doc910A design doc exists to be criticised before code exists. If a reviewer cannot find the weak point, the doc is hiding it, not resolving it.1112## Procedure13141. Open with the problem and the constraints, in numbers: current latency, volume, budget, deadline. No solution in the first paragraph.152. State the goals and, explicitly, the non-goals under a `## Non-goals` heading. "This does not handle multi-region" prevents scope arguments later.163. Present two or three real options, each with cost, complexity, and what it forecloses. A one-option doc is a decision already made.174. Recommend one and say why in terms of the constraints, not taste.185. Describe the proposed design with a diagram (text or ASCII), the data model, and the request path.196. List the failure modes and how the design handles each: what happens at 10x load, when a dependency is down.207. Call out the risks and the reversible decisions; mark the one-way doors.218. Give the migration and rollout plan, including rollback.229. Add an open-questions section with owners, so unresolved items are visible, not implied.2310. Estimate the cost and the operational burden (on-call, new dependency, runbooks to write).2411. Cap it at a few pages; link deep detail to appendices.2512. Circulate for async comment before review; the doc that gets no comments is either trivial or unread.2627## Pitfalls2829- A doc that opens with the solution, so options and tradeoffs read as rationalisation.30- Options listed but none costed, so the comparison is theatre.31- No non-goals, inviting scope creep in review.32- Diagrams that omit the failure path, showing only the happy request.33- Silently burying the risky choice instead of flagging it as a one-way door.34- A design that ignores the migration of existing data, treating greenfield as the only case.35- Estimating effort in days without a range or the assumptions behind it.3637## Verification3839 wc -l design.md && grep -cE '^#{1,3} (Non-goals|Options|Risks|Rollback)' design.md4041The doc has explicit Non-goals, Options, Risks and Rollback sections. Ask a reviewer to name the design's weakest point; if they cannot from the doc alone, add the tradeoff you left implicit.