Design docs people actually read

Most design documents are written to satisfy a process and read by nobody. You can tell because the comments cluster in the first two pages and stop.

A design doc that works has a different shape, and the shape follows from being honest about why you are writing it.

why you are actually writing it#

Three reasons, and they want different documents:

To think. Writing forces you to discover that your plan has a hole. This version is for you and can be messy.

To get input before it is expensive. The highest-value function. You want the person who knows the thing you do not know to tell you before you build.

To create a record. So that in two years, someone can find out why.

Most templates optimize for the third and produce documents that fail at the second. The record is only worth having if the decision was good, and the decision is good because of the input.

the format#

One page. Two if the problem genuinely needs it. Structured so a reader can stop after any section and have gotten something.

Problem. What is wrong right now, with evidence. Not "we should improve X" — what breaks, how often, who it affects. If you cannot state the problem concretely, the design is premature.

Goals and non-goals. The non-goals are the important half and almost always missing. "This does not address the reporting pipeline" prevents forty comments about the reporting pipeline.

Proposal. What you are going to build, in enough detail to disagree with. Interfaces, data shapes, the sequence of operations. A diagram if the shape is not obvious in prose.

Alternatives considered. Two or three, each with one honest sentence about why not. This is the section that gets the good comments, because it is where a reader sees the option you dismissed for a reason they know is wrong.

If your alternatives section contains obvious strawmen, experienced readers will notice and discount the whole document.

Risks and open questions. What might go wrong. What you are unsure about. This is where you ask for help explicitly, and it is where the people who know things will engage.

Rollout. How it ships, how it is verified, how it is rolled back. A design without a rollback plan is not finished.

That is it. Under a thousand words for most things.

the things that make people not read it#

Length. Past about two pages, readership drops sharply. If you need more, put the detail in an appendix and keep the main document short.

Burying the proposal. If the reader has to get through three pages of background before learning what you want to do, they will not.

No clear ask. Say what you want. "I need someone who knows the payment path to confirm the idempotency assumption in section 3" gets a response. "Please review" does not.

Passive voice throughout. "It was determined that" hides who decided and why. It also reads as evasive, because it usually is.

No deadline. "Comments by Thursday, I will start Friday" produces comments by Thursday. An open-ended review produces comments never.

the review that works#

Ask specific people specific questions. Not "posting this to the channel." Three named people, each with a sentence about why you want their input.

Give a real window. Three to five days. Long enough to fit into someone's week, short enough to stay on the top of the pile.

Timebox the meeting, if there is one. For a contentious design, a 30-minute discussion after people have read it resolves more than two weeks of comments. For an uncontentious one, do not have a meeting.

Record the decision at the top when it is made. A resolved design doc should start with "Decision: we are doing X, decided 2026-03-18, because Y." The person finding this in 2028 wants that sentence and nothing else.

the thing that makes them worth writing#

The value is not the document. It is that you discovered the flaw while writing rather than while implementing, and that someone who knew something told you before you had built the wrong thing.

If you write a design doc and nothing changes as a result, either your design was already right — possible, uncommon — or nobody engaged, and the process is theater.

Measure it that way: how many of your design docs changed the design? If the answer is none, stop writing them in this format and figure out what would actually get you input.