Design Docs and RFCs That Get Read

Scenario

Example team: the payments team must add support for partial refunds. One engineer writes a 22-page design doc with sequence diagrams for every endpoint. It sits in review for three weeks; the only comments are about formatting. The real risk — refunds racing with chargebacks — is discovered in production.

What you see on the team

• Design docs that are either missing ("we'll figure it out in code") or enormous.
• Reviews with few comments, mostly cosmetic.
• Decisions re-opened after implementation starts, because the people affected never read the doc.
• Nobody can find why a past design was chosen.

The common mistake

Writing design docs as specifications of the solution rather than as arguments about trade-offs, and sending them to everyone instead of the people who must decide.

Why it happens

Docs feel like proof of diligence, so authors optimise for completeness. But reviewers' attention is limited; long docs get skimmed. Malte Ubl's Design Docs at Google describes the design doc's job as documenting "key design decisions with emphasis on the trade-offs that were considered" — the trade-offs, not every endpoint.

The playbook

Use a short, fixed structure (adapted from Design Docs at Google):

Title, author, reviewers, status, date

1. Context and scope      - what exists, what's being built (half a page)
2. Goals and non-goals    - bullets; non-goals prevent scope creep
3. The design             - the approach and the key decisions
4. Alternatives considered- 2-3 options and why they lost (trade-offs!)
5. Risks and open questions - what could go wrong, what we don't know
6. Rollout and rollback   - how we ship it safely

Write when the problem is non-trivial: new service or data model, cross-team impact, security or money, hard-to-reverse choices. For small changes, a good PR description is enough.

Name reviewers and a deadline. Two to four people who will be affected or have the expertise; a decision date (e.g. "comments by Thursday, decision Friday").

Ask specific questions. "I'm least sure about the chargeback race in section 3 — is a row lock on the payment enough?"

Record the decision in the doc (status: accepted) and, for lasting choices, in an ADR (next lesson).

What to say

Review request:

"Design for partial refunds — 4 pages. Reviewers: Ana (ledger), Tom (risk), Lee (support tooling). I'd especially like eyes on the chargeback race in section 3 and the rollback plan. Comments by Thursday; I'll make a call Friday and note open disagreements."

Trade-offs

• Writing takes time — usually less than a wrong implementation.
• Fixed templates can feel rigid; keep sections short and allow "n/a".
• RFCs open to the whole org gather more input but slow decisions; use open RFCs for org-wide standards, targeted reviewers for team designs.

Signals it's working

• Docs are typically 2–6 pages and get substantive comments on trade-offs.
• Decisions are made by the stated date.
• Surprises after implementation starts become rare.
• New joiners find past decisions by searching the docs.

Key points

• A design doc is an argument about trade-offs, not a full specification.
• Use a short structure: context, goals/non-goals, design, alternatives, risks, rollout.
• Name a few reviewers, ask specific questions, set a decision date.
• Record the outcome; lasting decisions also go into an ADR.