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.

Quick check

3 questions from the related lessons. Answers are explained, and the ones you get right count towards your progress.

Question 1

Q1.Why do good design docs include non-goals?

Question 2

Q2.A bet has a 60% chance of gaining $500,000 and a 40% chance of losing $200,000. What is its expected value, in dollars?

Question 3

Q3.Which opening line follows BLUF?

Practice this in a lesson

Each engMBA lesson pairs a short explanation with practice questions that grade themselves. Free, with no signup.

See the full curriculum

Keep reading