Writing design docs for reviewers

Reviewers skim. Lead with the decision. A doc that buries the punchline on page four wastes senior time and gets shallow comments.

A strong doc lets a staff engineer review your approach in twenty minutes instead of pairing for an afternoon. That is how you get senior attention without blocking on their calendar.

The big idea

Put the recommendation in the first screenful, then expand.

We propose adding a Redis cache-aside layer in front of the product service for reads, with TTL 5 minutes and delete-on-write. Expected win: p99 from ~180 ms to ~40 ms at ~80% hit rate.

A skimmer now knows the move, the number, and the failure mode to hunt. The rest of the doc earns that sentence.

Walking through a reviewer's first minute

A reviewer asks three questions, in order:

1. What are you deciding? If this takes a scroll, rewrite the opening.
2. What numbers make it true? QPS, payload size, storage growth per year, cost order of magnitude, blast radius if the new dependency dies.
3. What could go wrong? Risks and rollback, not adjectives.

A sequence diagram for the hot path, a box diagram for ownership boundaries, and a table of SLOs beat three pages of prose.

Tone

Write as a peer asking for scrutiny, not a salesperson closing a deal. "I am unsure about X — please push back" invites better review than "obviously we must." Where to draft vs store the approved doc is covered in when to write.

Common mistakes

• Throat-clearing first page. History of the team, then the problem, then maybe the ask. Cut it. Decision first.
• Adjectives instead of numbers. "Much faster" and "highly available" are not reviewable.
• One giant diagram. If every box needs a footnote, split the doc.

Check yourself

Your opening paragraph explains how the current system evolved over three years. What should replace it?

The recommendation, the expected numbers, and the main risk — in the first screenful.

A reviewer says they cannot tell who owns the new cache. What did the doc miss?

An ownership diagram or a sentence that names the team and the rollback owner.

Key takeaways

• Lead with the decision. Support it with diagrams and numbers.
• Quantify load, size, cost, and blast radius.
• Ask for pushback. Advocacy reads as unfinished thinking.
• If it will not fit on one diagram, the doc is too big.

Further learning

Next, run the review so comments become decisions.

Companies Using RFCs or Design Docs (Pragmatic Engineer)What companies follow an RFC-like process, and what are templates and examples to get inspiration from?The Pragmatic Engineer