The Complete Guide to Design Docs: Documents That Preserve Decisions and Documents That Vanish

• Introduction
• 1. When to Write a Document and When Not To
  • 1-1. When You Can Skip It
  • 1-2. When You Must — Five Screening Questions
  • 1-3. The Common Mistake
• 2. Four Document Types and How to Pick One
  • 2-1. 1-pager — Agreeing That the Problem Is Real
  • 2-2. Design Doc — Implementation Strategy and Trade-offs
  • 2-3. ADR — One Decision as an Immutable Record
  • 2-4. RFC — Agreement Across Organizational Boundaries
  • 2-5. Which One, When
  • 2-6. A Contested Point — Heavyweight RFC vs Lightweight ADR
• 3. The Standard Sections and What Each One Actually Does
  • 3-1. Four Lines the Header Must Carry
• 4. Non-Goals and Alternatives Considered — the Two Boxes Most Often Empty
  • 4-1. Non-Goals Are Not a List of Things You Are Not Doing
  • 4-2. The One Anti-Pattern in Alternatives Considered
  • 4-3. The One Alternative You Must Always Include
• 5. Running the Review
  • 5-1. Speed Breaks Before Quality Does
  • 5-2. Lower the Approval Bar to Keep Reviews Moving
  • 5-3. Three-Stage Review
  • 5-4. Label Comments in Three Kinds
  • 5-5. Decision Deadlines
• 6. Decisions Have an Expiry Date — ADR Status Transitions
  • 6-1. Write the Re-Evaluation Trigger Alongside the Decision
  • 6-2. The Link Back to Section 4-2
• 7. Documents Go Stale — What to Do About It
  • 7-1. Three Strategies and What They Fit
  • 7-2. Cheap Devices for Detecting Staleness
  • 7-3. Deletion Is Also Maintenance
• 8. The Ways Documents Fail
  • 8-1. The Implementation Manual
  • 8-2. Approval Theater
  • 8-3. Straw-Man Alternatives
  • 8-4. Unbounded Scope
  • 8-5. The Document With No Decision
  • 8-6. Review Stalls
  • 8-7. Decisions That Live Only in Chat
  • 8-8. Documents That Outlive the Code and Lie
  • 8-9. The Claim That Design Docs Slow Teams Down
• Quiz: Check Your Understanding
• Conclusion
• References
• Further reading

Introduction

Design documents end up in one of two piles. There are documents that answer the question "why did we build it this way?" six months later, and documents whose link nobody can find by then. The difference is not prose quality. It is what got recorded, and where in the organization that record is anchored.

This blog already has Persuasive Writing for Engineers — how design docs and RFCs get approved and Writing as an Engineering Skill. Those two posts are about rhetoric and approval: how to write so people read, and how to get a document through. This post covers what comes before and after. It treats a document not as prose but as the team's decision-making infrastructure, and works through which format to use when, how to run the review as a process, how a decision expires, and the ways documents fail. The goal is not a well-written document but a document that preserves a decision.

The anchor reference is "Design Docs at Google." Definitions are quoted from it, but the weight here falls on the boxes that stay empty in practice and the procedures that collapse most often.

1. When to Write a Document and When Not To

"Design Docs at Google" defines a design doc as an informal document written before coding, and says what it should carry is "the high level implementation strategy and key design decisions with emphasis on the trade-offs." The same article says an engineer's job is "not to produce code per se, but rather to solve problems." Put those two sentences together and you get the criterion. No trade-offs, no document.

1-1. When You Can Skip It

• The solution is obvious and has no meaningful trade-offs. This is the skip condition the source names directly.
• The document would really be an implementation manual. A document that transcribes code into prose gives reviewers nothing to judge. Writing the code is faster.
• Reversing the change costs one person half a day. Trying it and deleting it if it fails is cheaper.

1-2. When You Must — Five Screening Questions

Two or more yes answers means write the document. One yes is often enough for a 1-pager. Zero means write code first.

1-3. The Common Mistake

Many organizations decide document-or-not by size: "anything over three weeks needs a design doc." Size is only a proxy. Three weeks of repetitive work needs no document; a half-day change to a storage format does. The real criteria are cost of reversal and the existence of alternatives.

2. Four Document Types and How to Pick One

The phrase "design document" covers four different objects. Blur them together and the document does no work at all.

2-1. 1-pager — Agreeing That the Problem Is Real

• Purpose: agree on the existence and priority of the problem, not the solution
• Length: one page. Background, symptoms, blast radius, cost of doing nothing, next step
• Lifetime: days to weeks. It gets promoted to a design doc or discarded
• Failure mode: writing the solution in advance, which skips the problem-definition discussion

2-2. Design Doc — Implementation Strategy and Trade-offs

• Purpose: agreement on how to build it. The "implementation strategy and key design decisions" from the source
• Length: usually a few pages. It scales with uncertainty, not with system size
• Lifetime: the implementation period. Usually frozen once that ends
• Failure mode: a conclusion with no alternatives analysis

2-3. ADR — One Decision as an Immutable Record

• Purpose: pin down the context, choice, and consequences of a single decision
• Length: one screen. Context, decision, consequences, status
• Lifetime: permanent. You never edit the body; you supersede it with a new ADR
• Failure mode: writing an explanation instead of a decision, so nobody can tell what was settled

2-4. RFC — Agreement Across Organizational Boundaries

• Purpose: set a standard or direction that spans multiple teams and systems
• Length: longer than a design doc. A rollout plan and a list of affected teams are mandatory
• Lifetime: a reference document after approval. Revisions are issued as new documents
• Failure mode: the process is so heavy nobody starts one, or the form survives while the real agreement happens in chat

2-5. Which One, When

2-6. A Contested Point — Heavyweight RFC vs Lightweight ADR

The industry genuinely disagrees here. Rather than pick a winner, look at the axes.

• Decision frequency: frequent decisions turn a heavy process into a bottleneck. Rare and large decisions make the process cost relatively small.
• Stakeholder dispersion: with a single-digit number of teams bound by the decision, conversation can substitute for process. Past double digits, conversation cannot reach everyone.
• Cost of reversal: an RFC on a reversible decision slows down learning.
• Cost of upkeep: ADRs are cheap to write and therefore easy to abandon. RFCs are expensive to write and stay visible longer.
• Organizational trust level: in a low-trust organization, a lightweight process resolves into "nobody knows who decided this or when."

Plenty of organizations run both. An RFC sets the direction, and inside that direction each team records its detailed choices as ADRs.

3. The Standard Sections and What Each One Actually Does

The typical structure "Design Docs at Google" lists is Context and Scope, Goals and Non-Goals, The Actual Design, Alternatives Considered, and cross-cutting concerns such as security, privacy, and observability. Copying the shell does nothing, so here is each box rewritten as the function it performs.

[Header]  Title / Author / Last updated / Status / Review deadline

1. Context and Scope        why this problem exists now
2. Goals                    what must become true for this to be a success
3. Non-Goals                things that could reasonably have been goals but are not
4. The Actual Design        the design and the trade-offs inside it
5. Alternatives Considered  what was considered and rejected, and under what conditions
6. Cross-cutting concerns   security / privacy / observability / operations

• Context and Scope: fill in only the minimum background a reviewer needs to judge. Its job is to close the knowledge gap between author and reader. The moment you start writing company history, it has failed.
• Goals: give reviewers a ruler for evaluating the design. A goal of "improve performance" is no ruler at all. "Get p99 latency under 800ms" is decidable.
• Non-Goals: lock the scope. Covered separately in the next section.
• The Actual Design: this is the body. Its job is not to explain structure but to present the trade-offs. Data flow, storage model, failure behavior, and migration path belong here.
• Alternatives Considered: prevents the argument from reopening. Also covered in the next section.
• Cross-cutting concerns: pre-empts the questions another part of the organization will certainly ask later. Leave it blank and a security review lands after the design review is over, pushing the schedule again.

3-1. Four Lines the Header Must Carry

Status (draft, in review, accepted, deprecated), last updated, owner, review deadline. Without these four lines, a reader six months later cannot judge whether to trust the document. The presence of those four lines affects document lifetime more than the quality of the body does.

4. Non-Goals and Alternatives Considered — the Two Boxes Most Often Empty

4-1. Non-Goals Are Not a List of Things You Are Not Doing

A Non-Goal is something that could reasonably have been a goal but is not one this time. Listing things nobody expected in the first place only fills the box.

• Bad Non-Goal: "this system does not control spacecraft"
• Good Non-Goal: "multi-region concurrent writes are out of scope. We go with single-region writes plus asynchronous replication"
• Good Non-Goal: "improving latency on the existing v1 API is not a goal. Only the v2 path is in scope"

Good Non-Goals share one property: the reader feels a twinge of disappointment. If nobody is disappointed, you have not locked any scope.

4-2. The One Anti-Pattern in Alternatives Considered

The most common failure is the straw-man alternative built so your own option wins. If you list three and two are obviously bad, the document did not evaluate alternatives; it decorated a conclusion.

Forcing one line under each alternative fixes most of it.

What would have to be true for alternative B to win?
→ "If write QPS grew 10x and the team added two more operators, B would be better."

That one line does three jobs at once. First, it is evidence the alternative was taken seriously. Second, when circumstances change six months later, the re-evaluation trigger is already written down. Third, it gives reviewers something concrete to disagree with. "Wouldn't B be better?" becomes "your 10x QPS assumption is wrong."

4-3. The One Alternative You Must Always Include

Doing nothing. Write down what it keeps costing to stay where you are, and the project's justification gets tested. Filling in this box does occasionally cancel a project, and that is the document doing its job.

5. Running the Review

Document reviews fail almost exactly the way code reviews do. The principles Google's engineering practices set out for code review transfer directly.

5-1. Speed Breaks Before Quality Does

• "Speed of Code Reviews" states flatly that "one business day is the maximum time it should take to respond to a code review request." It also says that if you are not in the middle of a focused task, you should review shortly after the request arrives.
• The same document says "most complaints about the code review process are actually resolved by making the process faster."
• It also notes that slow reviews "discourage code cleanups, refactorings, and further improvements to existing CLs."

Translated to documents: in an organization with slow reviews, people stop writing documents. The first cause of death for a documentation culture is not the burden of writing but response latency.

5-2. Lower the Approval Bar to Keep Reviews Moving

"The Standard of Code Review" says reviewers "should favor approving a CL once it is in a state where it definitely improves the overall code health of the system being worked on, even if the CL isn't perfect." The same applies to documents. The approval bar is improvement, not completeness. Wait for the perfect document and it stays a draft forever.

The rest of that document holds too. Technical facts and data beat personal preference. Non-mandatory polish is prefixed with "Nit: " so the author may ignore it. And it says explicitly: "Don't let a CL sit around because the author and the reviewer can't come to an agreement." That clause matters even more for documents. If you have not decided in advance who decides when agreement fails, the document stays open forever.

5-3. Three-Stage Review

The document lifecycle "Design Docs at Google" describes is creation and rapid iteration, then review, then implementation and iteration, then maintenance and learning. Splitting the review stage into three layers raises the pass rate sharply.

1. One-person review: send it first to the single person most likely to object. Half the problems die here.
2. Small-group review: the three to five people directly affected. Run it as asynchronous comments.
3. Broad announcement: send everyone else the link plus a decision deadline. No objection means it passes.

Hold a meeting only when asynchronous review fails to converge. When objections split into two camps and comments pass twenty, that is when a 30-minute meeting earns its place.

5-4. Label Comments in Three Kinds

• Blocking: a reason this cannot ship as written. Must be resolved before approval
• Question: something unclear. Can be closed by an answer
• Preference: "I would have done it differently." The author may ignore it

Without labels, every comment reads like a blocker. Organizations where document review feels frightening are usually organizations without these labels.

5-5. Decision Deadlines

Use a deadline instead of a quorum. Write at the top of the document: "if there are no objections by 6pm on August 20, we proceed with this option." A quorum lets one busy person hold a document hostage indefinitely; a deadline converts silence into explicit consent.

6. Decisions Have an Expiry Date — ADR Status Transitions

The point of an ADR is not the format but the immutability. Edit the body of a decision already made and you erase the constraints under which it was made. Because a decision's rationale is bound to the constraints of its moment, when the constraints change you do not amend the decision — you make a new decision and mark the old one as superseded.

Proposed ──accept──▶ Accepted ──replace──▶ Superseded (by ADR-0031)
    │                   │
    │ reject            │ no longer followed (no replacement)
    ▼                   ▼
 Rejected           Deprecated

• Proposed: submitted, under review
• Accepted: settled. The decision currently in force
• Rejected: considered and not adopted. Do not delete it. This record is worth the most when the same proposal comes back
• Deprecated: no longer followed. No replacement
• Superseded: replaced by a new ADR. Always record the replacing ADR number

6-1. Write the Re-Evaluation Trigger Alongside the Decision

Date-based expiry ("revisit in a year") almost never happens. It has to be a condition for the alarm to ring.

# ADR-0012: Use a relational database for order state

- Status: Accepted (2026-08-15)
- Deciders: Payments team
- Re-evaluation trigger: orders table exceeds 500M rows, or write QPS exceeds 3,000

### Context
Current volume is 400K orders per day, peak write QPS 120. The transaction boundary spans orders, payments, and inventory.

### Decision
A single relational database instance plus read replicas.

### Consequences
- Better: transaction boundaries do not have to be handled in application code
- Worse: write scaling is tied to vertical scaling
- Metrics to watch: write QPS, table row count, replication lag

Put the metrics named in the trigger on an actual dashboard and the document stays alive. Without that link, the trigger is just a sentence.

6-2. The Link Back to Section 4-2

The line forced under each alternative in 4-2 — "what would have to be true for this to win?" — becomes the re-evaluation trigger verbatim. A sentence written once in the design doc gets reused as the ADR's expiry condition.

7. Documents Go Stale — What to Do About It

"Design Docs at Google" admits design docs "like all documentation, tend to get out of sync with reality over time," and offers updating the original or amending and linking follow-ups. This problem cannot be eliminated; you only get to choose how to manage it.

7-1. Three Strategies and What They Fit

The most common mistake is trying to keep a design doc alive. A design doc is a record of judgment at a point in time. Keep editing it and you lose the answer to "as of when is this document true?" Freeze it when implementation ends and announce what changed in one line at the top.

> This document reflects the design as of 2026-08-15. The cache layer was
> replaced by ADR-0031 on 2026-11-02. See that document for the current shape.

7-2. Cheap Devices for Detecting Staleness

• Last reviewed date: record the review date, not the edit date. Even when nothing changed, you need the date somebody confirmed "still valid."
• Orphan detection: when an owner leaves or moves, flip the document status to "unowned" automatically.
• Distance from the code: a document inside the code repository is visible during changes. A document in a separate wiki is not. This single factor changes the rate of decay dramatically.
• Link rot checks: periodically verify the links inside the document. Broken links are the most reliable signal that a document has been abandoned.

7-3. Deletion Is Also Maintenance

Do not delete a retired document. Flip its status to deprecated and remove it from search. Deleting breaks links; leaving it circulates wrong information. Status plus search exclusion is the compromise.

8. The Ways Documents Fail

Eight failure modes, each as symptom, cause, and response.

8-1. The Implementation Manual

• Symptom: the document transcribes code into prose. There is no trade-off paragraph
• Cause: the document was written to fill a form after the decision was already made
• Response: as the source says, do not write this document — start coding

8-2. Approval Theater

• Symptom: eight approvals, zero comments
• Cause: review has become a rite of passage. Objecting is expensive in this culture
• Response: put a one-person review in front, and introduce blocking/question/preference labels to lower the cost of objecting

8-3. Straw-Man Alternatives

• Symptom: two of the three alternatives are obviously bad
• Cause: the conclusion came first and the rationale was manufactured
• Response: force "what would have to be true for this to win?" under every alternative

8-4. Unbounded Scope

• Symptom: Non-Goals is empty and review comments fill up with new requirements
• Cause: the scope was never locked
• Response: write at least three Non-Goals that make the reader feel a twinge of disappointment

8-5. The Document With No Decision

• Symptom: excellent background, no way to tell what was settled
• Cause: information-sharing documents and decision documents were never distinguished
• Response: write "the decision this document is trying to settle" in one sentence at the top

8-6. Review Stalls

• Symptom: documents pile up in draft state for three weeks or more
• Cause: response latency and an absent decision-maker
• Response: adopt a one-business-day response standard and a decision deadline

8-7. Decisions That Live Only in Chat

• Symptom: the document says option A, the code does option B, and the rationale is in a chat thread from three months ago
• Cause: post-review changes never got reflected in the document
• Response: make adding one ADR a release condition whenever the design changes during implementation

8-8. Documents That Outlive the Code and Lie

• Symptom: a new hire builds to the document and the real system differs
• Cause: no status or review date, so trustworthiness cannot be judged
• Response: enforce the four header lines and an explicit deprecated status

8-9. The Claim That Design Docs Slow Teams Down

This is also contested. One side says writing and reviewing delays the start; the other says burning three weeks in the wrong direction costs more than two days of writing. There are three axes. Cost of reversal (when it is cheap, experimenting beats documenting), number of stakeholders (when it is large, agreement is unreachable without a document), and review response speed (in a slow organization, documents really do become the bottleneck). The third axis matters most. Slowness is often caused by review latency rather than the document itself, and if so the thing to fix is the response time, not the documentation policy.

Quiz: Check Your Understanding

Conclusion

What a document is trying to preserve is not an explanation but a decision and the conditions of that decision. With the conditions written down, the document announces its own expiry; without them, it quietly becomes a lie.

The three cheapest improvements in practice are these. First, enforce the four header lines — status, last reviewed, owner, decision deadline — on every document. Second, attach "what would have to be true for this to win?" to every alternative. Third, set review response time at one business day and actually measure it. None of the three lengthens the template, and all three extend document lifetime substantially.

Formats will differ by organization. But a document that cannot answer "what was decided," "why was it decided that way at the time," and "when should we look at it again" is a document that vanishes, whatever its format.

References

• Design Docs at Google — Industrial Empathy (Malte Ubl) — quoted for the definition of a design doc (implementation strategy with emphasis on trade-offs), the line that an engineer's job is problem-solving rather than producing code, the standard sections (Context and Scope / Goals and Non-Goals / The Actual Design / Alternatives Considered / cross-cutting concerns), the conditions under which you can skip a doc, the document lifecycle, and the problem of documents drifting out of sync with reality. Retrieved 2026-08-15.
• The Standard of Code Review — Google Engineering Practices — the "approve once it definitely improves overall code health, even if not perfect" principle, technical facts over preferences, the "Nit: " prefix, and the instruction not to let a change sit because author and reviewer cannot agree, applied here to document review. Retrieved 2026-08-15.
• Speed of Code Reviews — Google Engineering Practices — the one-business-day response standard, "most complaints are actually resolved by making the process faster," and the point that slow reviews discourage cleanups and refactorings. Retrieved 2026-08-15.
• The four-format comparison table, the five screening questions, the three-stage review, the comment labelling scheme, the practice of wiring re-evaluation triggers to a dashboard, and the eight failure modes are not taken verbatim from the sources above; they are the procedure organized in this post.

Further reading

• Related post on this blog: Persuasive Writing for Engineers — how design docs and RFCs get approved
• Related post on this blog: Writing as an Engineering Skill
• Related post on this blog: The Conversational Side of Code Review
• Related post on this blog: Technical Debt in Business Language
• Related tool: Collab RPG

Complete Guide Series

• Next: The Complete Guide to API Design: Settle the Irreversible Decisions First