# How do I write a design doc that gets a decision?

> Open with the decision, the people who make it and the date, then give the options with their costs, one recommendation, and a review that ends

- Author: Ash Gaikwad (https://ashgaikwad.com)
- Published: 2022-04-08
- Topics: design docs, engineering leadership, architecture, staff engineer
- Canonical: https://ashgaikwad.com/blogs/how-do-i-write-a-design-doc-that-gets-a-decision

A design doc that gets a decision opens with the decision it needs, names the person who makes it and the date, and then shows the options with their costs and one recommendation. The review runs until that date and ends with a yes or a no that is written down. Everything else in the doc is there to help one person say yes or no with their eyes open.

I am Ash, a Staff engineer in Toronto. At a company I worked at, I led a team of 7 that restructured a tangled MVC codebase in place with domain-driven design, and I wrote the architecture documents and ran the design reviews. At another company I worked at, I mentored 5+ engineers, ran design reviews, and wrote down the standards that took new-hire onboarding from 3 weeks to 2 days. In my current job I introduced spec-first development with coding agents, and I got the plan for a move from a monolith to services agreed with product, design, support and engineering leadership. This article is for engineers and tech leads whose design docs collect comments but no answer. The method comes from published process documents, which I link, and where something is my opinion I say so.

![The order I put a design doc in so that it ends in a decision. It opens with the decision needed, who decides and by when. Then come the options with their costs, my recommendation and the non-goals. A review runs until a comment date. The decider answers yes or no, and the answer is saved as a short decision record.](/images/blogs/design-doc-that-gets-a-decision.svg)

## What a design doc is for

A design doc exists to settle a question while settling it is still cheap. [Design Docs at Google](https://www.industrialempathy.com/posts/design-docs-at-google/) describes it as a document that records "the high level implementation strategy and key design decisions with emphasis on the trade-offs that were considered during those decisions." Two of the functions it lists are "Early identification of design issues when making changes is still cheap" and "Achieving consensus around a design in the organization."

Read that as a test. If your doc explains how the system works but never says what you want people to decide, it is documentation, and the reader does not know what to do with it. People leave comments because comments are all they can do. A decision gives the reader a job.

## Open with the decision, the decider and the date

Put a short block at the top of the page, before the background. In my opinion it needs five lines. The decision you need, written as a question with a yes or a no, such as "Do we move the checkout code into its own module this quarter?" The person who decides. The date when comments close. Your recommendation in one sentence. And the status, which starts as proposed.

Established projects do the same. The [Kubernetes enhancement process](https://github.com/kubernetes/enhancements/blob/master/keps/sig-architecture/0000-kep-process/README.md) says the approvers "are the individuals who decide when to move this KEP to the implementable state", and that approvers "should be a distinct set from authors." The [Rust RFC process](https://rust-lang.github.io/rfcs/0002-rfc-process.html) says that "somebody on the core team will either accept the RFC by merging the pull request" or "reject it by closing the pull request." In both, a named person or group says yes or no, and it is not the author.

A doc with no decider cannot end, and comments arrive forever if there is no date. I would talk to the decider before sharing the draft.

## Show the options with their costs

The options do the most work. The Google article says that alternatives considered "is one of the most important ones as it shows very explicitly why the selected solution is the best given the project goals". Oxide's [RFD 1](https://rfd.shared.oxide.computer/rfd/0001) asks authors to "Document the viable options (or a subset of options if we can easily rule some out) and the benefits and drawbacks of each option", so that "our future selves (and those who join in the future)" can see what was decided and why.

Write each option so that a sceptic can see its cost. Say what it costs to build, to run, what it makes harder later and what it needs from other teams. Use the same criteria for every option so a reader can lay them side by side. In my opinion "do nothing" belongs on the list every time. The decider is thinking about it anyway, and writing down its cost is often the strongest argument for the change, or the honest reason to drop it.

Then recommend one. Do not make the reader guess which you prefer, and say which trade-off you accept. A sentence such as "I recommend option B because switching later is cheap and the extra on-call load is small" shows judgement, which is what a decider is paying for.

## Add the rest, and keep it light

Below the top block, give a short problem statement with what happens if you do nothing. Add the requirements and constraints, and mark which are hard and which are preferences. Describe the design at the level the decision needs, then the risks, the rollout and how you would roll it back. Google asks for cross-cutting concerns, "where your organization can ensure that certain cross-cutting concerns such as security, privacy, and observability are always taken into consideration." For interfaces and schemas, it says to "focus on the parts that are relevant to the design and its trade-offs".

Finish with the open questions and give each an owner and a date. Separate the ones that must be answered before the decision from the ones that can wait for implementation, or every open item becomes a reason to delay. Add how you will know it worked. And share a rough draft early. The reviewers can correct the question before you have spent a week polishing the answer.

## Say what you are not doing

Add a short list of non-goals. Google defines them as "things that could reasonably be goals, but are explicitly chosen not to be goals." "The system should not crash" is a negated goal and adds nothing. "This design does not handle multi-region failover" tells a reviewer which argument to skip. When a reviewer asks for something on the list, you point to the line, and the talk becomes whether to change the list, which is a decision someone can make.

Keep the doc short as well. Google puts the sweet spot for a larger project at "around 10-20ish pages" and says a "1-3 page “mini design doc”" works for smaller changes. Michael Nygard, in his post on [documenting architecture decisions](https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions), says it bluntly: "Nobody ever reads large documents, either."

## Run the review so that it ends

The Google article warns that reviews "can add a lot of value, but they are also a dangerous trap of overhead, so treat them wisely." It says the value is timing: "The primary value of the review isn’t that issues get discovered per-se, but rather that this happens relatively early in the development lifecycle when it is still relatively cheap to make changes."

So a review finds the expensive mistakes early, and then it should stop. I would circulate the doc on paper first, with the comment date from the top block. Ask for specific things, such as which assumption is wrong and what would stop you approving. Hold a meeting only for the points where people still disagree.

When the date arrives, the decider answers: yes, no, or yes with named changes. The status changes and someone writes one line of why. If an objection is not accepted, say so in the doc with the reason, so it is answered and not forgotten. I wrote about running reviews without becoming the person every review waits for in [how a tech lead can coordinate several teams without becoming the bottleneck](/blogs/how-can-a-tech-lead-coordinate-several-teams-without-becoming-the-bottleneck).

## What it costs, and what I would not do

A design doc is overhead. Google says docs "save money, because they avoid going down coding rabbit holes" and "cost money, because creation and review take time." The Kubernetes process lists the same worry among its drawbacks, saying "we may find that the KEP process introduces an unreasonable bottleneck on our development velocity." Expect that cost and decide it is worth paying.

There are four things I would not do. I would not write a long doc to look thorough, because a long doc is not read. I would not wait for everyone to agree, because one person who owns the decision is faster than a crowd. I would not hold the meeting before the document exists, because a meeting without a written proposal becomes a tour of everyone's preferences. And I would not let the doc drift from the code, because a stale decision misleads the next reader.

## When not to write one

Do not write a doc when there is nothing to decide. Google says the test is "whether the solution to the design problem is ambiguous", and warns about docs that are implementation manuals. If the doc says how you will build it and has no trade-offs, write the code. Google also says a doc is worth it when the design is "ambiguous or even contentious".

Size matters too. The Rust process applies only to "substantial" changes and excludes "Rephrasing, reorganizing, refactoring" where meaning does not change. Oxide says to "use your best judgement when it comes to the level of depth to devote to an RFD." A one-page doc for a small decision is fine, and a prototype can answer a question faster.

## Design doc, RFC or decision record?

The names overlap, and the difference is the job each does. A design doc and an RFC (request for comments) are both a proposal that people discuss before work starts. Oxide's RFD 1 calls its documents requests for discussion and says they follow "the original spirit of the IETF Request for Comments", and it lists "An architectural or design decision for hardware or software" among its uses.

An architecture decision record (ADR) is a different job. Nygard's version is a short text file with a title, context, decision, status and consequences. The context is "value-neutral", the decision is "stated in full sentences, with active voice" as "We will …", and "All consequences should be listed here, not just the “positive” ones." The whole record "should be one or two pages long." The design doc argues, and the ADR records the result.

ADRs are cheap to keep. Nygard stores them in the project repository, numbers them in sequence, and when a decision is reversed, "we will keep the old one around, but mark it as superseded." His reason is that a person who finds a decision without its reasons can only blindly accept it or blindly change it.

## How to tell that it worked

Look for three signs. Decisions are made by the date written in the doc. The same question is not reopened a month later without new facts. A new engineer can find the reason for a choice in minutes. Google adds a check for the author: "re-read your own design docs a year or 2 later".

## A plan for the first week

1. Pick one open decision that keeps coming up in chat and write the question as a yes or no.
2. Write the top block with the question, the decider, the comment date, your recommendation and the status.
3. List two or three options, including doing nothing, with the same criteria for each, and add three non-goals.
4. Talk to the decider before you share it, then circulate the doc with the comment date.
5. On the date, get the answer, change the status and save a short ADR in the repository.

The same habit helps when you lead work across teams. In [how do I lead a technical initiative across several teams](/blogs/how-do-i-lead-a-technical-initiative-across-several-teams) I cover getting a sponsor and keeping groups current, and the design doc is where the agreement gets written down.

A design doc is finished when someone has decided, and not when it is polished.

## Frequently asked questions

### What should a design doc include?

Start with the decision needed, the decider, the comment date and your recommendation. Then add context, goals and non-goals, the options with their costs, the risks, open questions with owners, and cross-cutting concerns such as security and observability. Google's guide says "Rule #1 is: Write them in whatever form makes the most sense for the particular project", so keep the parts that help the decision.

### What is the difference between a design doc, an RFC and an ADR?

A design doc and an RFC are proposals that people discuss before work starts, and the names differ by organisation. An ADR records the decision that came out of it, in one or two pages, and lives with the code. In my opinion you write the doc to decide and keep the ADR so the decision can be found later.

### When should I not write a design doc?

When the solution is not ambiguous. Google says a doc that is an implementation manual with no trade-offs is a sign you should have written the program. Small changes can use a one-page version, and a quick prototype can answer some questions faster than a document.
