Communication
How to write a design doc that gets a decision made
How to write a software design doc or RFC that reviewers read and decide on: goals, non-goals, alternatives, a decision date, and when to use an ADR instead.
· 6 min read

A design doc is not documentation of what you were going to build anyway. It is an argument for a decision, written so that people who are not in the room — or in your time zone — can test it. The best ones are short, opinionated, and end with a decision on a known date.
When to write one
Write a design doc for decisions that are expensive to reverse: data models, public APIs, new infrastructure, anything another team will build on. For a small reversible choice, decide and move on. Jeff Bezos's one-way and two-way doors are a useful test.
The sections that matter
- Problem: what is wrong today, with numbers if you have them.
- Goals: what success looks like and how you will measure it.
- Non-goals: what this design deliberately does not solve. This saves more review time than any other section.
- Proposal: the design, at the level of detail reviewers need to judge it.
- Alternatives considered: each with the reason it was rejected.
- Risks and open questions: what could go wrong and what you do not know yet.
- Rollout: how you will ship it safely and how you would roll back.
Run the review like a project
Name the reviewers and the decision-maker at the top, with a decision date. Ten working days is plenty for most designs. Without a deadline, docs collect comments for weeks and decisions get made by whoever gives up last. Resolve comment threads explicitly, and if a disagreement will not converge in writing, hold one short meeting for that issue only.
Write it for the skimmer
Open with a two-paragraph summary that states the recommendation. Use headings a reader can scan. Put long benchmarks and background in an appendix. If your headings alone tell the story, the doc is in good shape.
ADRs: the lightweight cousin
An architecture decision record is a short markdown file in the repository that records one decision: the context, the decision and the consequences. ADRs are immutable — when a decision changes, a new record supersedes the old. A year later, when someone asks “why did we choose this?”, the answer is next to the code.
Teams that write decisions down argue less, onboard faster and repeat fewer mistakes. It is one of the cheapest ways to scale an engineering organization.



