Design docs that get approved

At staff level, much of your impact flows through documents: design docs, proposals, decision records. A good one gets a team aligned in a week; a bad one generates forty comments and a meeting that ends with “let’s take this offline”.

The difference is rarely writing quality. It’s whether the doc is built around a decision.

The one-page structure

1. Context

What’s true today, with numbers. Who’s affected. Why now.

Order events are published after the database commit. During deploys we lose events: 37 lost last month, each fixed by hand. Three teams consume these events.

(Numbers in examples are illustrative.) Two or three paragraphs. If the context is long, link to it.

2. Goals and non-goals

Goals are what success looks like, measurably. Non-goals are what this doc deliberately doesn’t solve.

Goal: no order event is lost on crash or deploy. Non-goal: exactly-once delivery; consumers already de-duplicate. Non-goal: migrating other event types this quarter.

Non-goals prevent half the review comments. “What about X?” — “Out of scope, see non-goals” is a much shorter conversation.

3. Options considered

At least two real options, plus “do nothing” when it’s plausible. A table makes trade-offs comparable:

A doc with one option isn’t a design doc; it’s an announcement, and reviewers will invent the alternatives for you in the comments.

4. The decision

State it plainly, and say why the winner wins for this context. “Outbox with polling: no new infrastructure, latency is acceptable for these consumers, and we can move to CDC later without changing producers.”

5. Risks and early signals

What could go wrong, and how you’ll notice early. “Outbox table growth — alert on oldest unpublished row older than 60 s; nightly cleanup job.”

6. Rollout and rollback

How it ships in steps, and how each step is undone. If the rollback is “restore from backup”, the rollout needs more steps.

That’s the whole doc. One to three pages. Diagrams are welcome where they replace paragraphs.

Running the review

The doc is half the work. The other half is how you take it through review:

1. Pre-read with the toughest reviewer, privately. The person most likely to object should see it first, one-to-one. Their objections improve the doc, and they arrive at the group review as a co-author rather than a critic.
2. Say what you need. “Looking for a decision between options A and B by Friday”, not “feedback welcome”.
3. Comments in the doc, decisions in the doc. When a thread resolves, update the text. A doc whose body disagrees with its comments confuses everyone who reads it later.
4. Time-box. If a review meeting is needed, 30 minutes, with the decision as the agenda.
5. Record the outcome. Add a short “Decision” block at the top with the date and who agreed. Six months later, that’s what people will look for.

Lightweight decisions: ADRs

Not every decision needs a full design doc. For smaller ones, an Architecture Decision Record — title, context, decision, consequences, in half a page, stored in the repo next to the code — is enough. The point is the same: future engineers can find why things are the way they are, instead of reverse-engineering it from the code or from someone’s memory.

Common reasons docs stall

Takeaways

• Build the doc around a decision, not a description.
• Non-goals and an options table do most of the work.
• Pre-review with the toughest reviewer first.
• Record the outcome where people will find it later.