Design Doc Authoring: RFCs, ADRs, and the Staff Engineer's Written Output

TL;DR: The whiteboard evaporates. The design doc persists. For a Staff+ engineer, the written artifact is the primary leverage: ADRs log single decisions in under a page, design docs align cross-team architecture in 10-20 pages^[1], and RFCs gate proposals through explicit lifecycle states. Google analyzed 141,652 approved design documents and found that structured review interventions reduced median time-to-approval by 25%^[2]. Master the format, the review culture, and the lifecycle, and your decisions compound instead of disappearing.

Learning Objectives#

After this module, you will be able to:

• Write a Nygard-format ADR in under 30 minutes
• Structure a design doc with the nine canonical sections (including Non-Goals and Alternatives Considered)
• Run an RFC through its lifecycle and give ask-don't-tell feedback
• Choose the right format (ADR, design doc, RFC, 6-pager) for a given decision scope
• Map doc output to level expectations from L4 to L7

Intuition#

You move into a new apartment. The previous tenant left no notes. The thermostat has three unlabeled modes. The breaker panel has 20 switches, none labeled. The garden hose connects to a valve you cannot find. You spend the first month reverse-engineering decisions someone else made years ago.

Now imagine the previous tenant left a binder. Page one: "We set the thermostat to mode 2 because mode 3 trips the breaker when the AC runs simultaneously. We considered replacing the breaker panel but the landlord refused." That is an Architecture Decision Record. It is short, it names the context, the decision, and the consequences, and it saves you a week of debugging.

A design doc is the blueprint you write before renovating the kitchen. It names what you are building, what you are not building, the alternatives you rejected, and how you will know it worked. An RFC is that blueprint submitted to the building committee for formal review before you start demolition.

The format differs. The purpose is identical: serialize a decision into prose so that reviewers can consent asynchronously and future readers can reconstruct intent. This chapter teaches you the dominant formats, the review culture that makes them work, and the anti-patterns that turn them into theater.

Theory#

Why design docs matter#

A design doc is a pre-implementation written artifact that captures context, goals, a proposed design, alternatives considered, and cross-cutting concerns. Its value is threefold.

First, writing is thinking. The act of serializing a plan into prose exposes logical gaps that diagrams and conversation hide. Malte Ubl frames this as "early identification of design issues when making changes is still cheap."^[1:1]

Second, async review scales past meeting bandwidth. A reviewer in Tokyo can engage before the author in New York wakes up. Uber's RFC process coordinated "dozens of systems and well over twenty engineering teams" in two months for their tipping launch.^[3]

Third, the doc survives personnel changes. At Google, "Where is the design doc?" is the standard first question when encountering an unfamiliar system.^[4] A whiteboard sketch does not survive a team reorg. A doc does.

The cost is real: creation overhead for obvious implementations, review latency if the team waits for weekly slots, and drift when docs are not updated alongside code. The skill is knowing when to write (one-way doors, cross-team changes) and when not to (two-way doors, trivial changes). Trade-off Thinking introduced the one-way/two-way door framework; design docs are the written process that one-way doors deserve.

ADR format and its variants#

Michael Nygard introduced Architecture Decision Records in 2011 as a reaction against large specifications that nobody updates: "Large documents are never kept up to date... small, modular documents have at least a chance at being updated."^[5]

The original template has five sections:

# ADR-NNN: Use Postgres as primary operational store

## Status
Accepted

## Context
We need ACID transactions for payment flows. Our team has 5 years
of Postgres operational experience. DynamoDB was considered but
lacks cross-item transactions without Streams workarounds.

## Decision
We will use PostgreSQL 18 with logical replication for read replicas.

## Consequences
Positive: familiar tooling, strong consistency, rich ecosystem.
Negative: vertical scaling ceiling around 100K TPS write;
we accept this given current 2K TPS volume.

Key properties: ADRs are immutable once accepted. If a decision is reversed, you write a new superseding ADR and mark the old one as superseded. The history is the value.^[5:1]

Nat Pryce's adr-tools (first commit 2016, with version 2.0 in February 2017 introducing the current CLI interface) automates this with a CLI: adr new Use Rust for performance-critical paths scaffolds a numbered file in doc/adr/.^[6]

MADR (Markdown ADR, Zimmermann and Kopp, 2017) extends Nygard with YAML frontmatter metadata (status, date, deciders, consulted, informed), a Decision Drivers section, explicit Considered Options with pros/cons, and a Confirmation section for validating compliance.^[7] Microsoft's Well-Architected Framework now officially recommends ADRs with the immutability rule: "write a new record that supersedes the original and link the two together."^[8]

ADRs are immutable once accepted; reversing a decision means writing a new superseding ADR, preserving the full decision history.

Design doc structure (Google-style)#

A full design doc runs 10-20 pages for a large project and 1-3 pages for incremental work.^[1:2] The canonical sections:

1. TL;DR - 2-3 sentences a VP reads in 20 seconds.
2. Context and Scope - what exists today, what is changing, who is affected.
3. Goals and Non-Goals - explicit outcomes this doc addresses, and what is deliberately excluded.
4. The Design - system-context diagram, APIs, data storage, degree-of-constraint discussion.
5. Alternatives Considered - 2-4 real options with trade-off analysis for each.
6. Cross-Cutting Concerns - security, privacy, observability, rollout, migration.
7. Open Questions - known unknowns and explicit decision requests.
8. Rollout Plan - phased deployment, success metrics, rollback triggers.
9. Document History - amendment links rather than inline edits.

Two sections separate senior from junior writing. The Non-Goals section names things that could reasonably be goals but are explicitly excluded. Ubl: "non-goals aren't negated goals like 'The system shouldn't crash', but rather things that could reasonably be goals, but are explicitly chosen not to be goals."^[1:3] The Alternatives Considered section is where you demonstrate that you explored the design space: "this section is one of the most important ones."^[1:4]

Trade-off Articulation covers how to structure the alternatives analysis itself. Diagramming Skills covers the visual artifacts that belong in the Design section.

RFC process across organizations#

An RFC (Request for Comments) adds process governance to a design doc: numbered identifiers, explicit lifecycle states, and formal disposition by a named decision body.

IETF (the origin): RFC 2026 defines the Internet Standards Track with minimum six-month soak at Proposed Standard and advancement requiring "at least two independent and interoperable implementations from different code bases."^[9] The procedural weight is extreme because it governs protocols used by thousands of vendors.

Rust RFCs: Fork the repo, copy the template, submit a PR. A sub-team proposes Final Comment Period (FCP) with a disposition (merge, close, postpone); all sub-team members must sign off; FCP lasts ten calendar days.^[10] The template mandates a Drawbacks section before Rationale and Alternatives, forcing the author to argue against their own proposal first.^[11]

Python PEPs: Three types (Standards Track, Informational, Process) with a PEP-Delegate (or the Steering Council) as decision-maker. Required sections include "How to Teach This" and "Rejected Ideas."^[12]

Go proposals: Start as a GitHub issue; discussion triages into accept, decline, or ask-for-design-doc. The design doc template adds a Compatibility section tied to Go's backward-compatibility promise.^[13]

Oxide Computer RFDs: "Request for Discussion" with six states (prediscussion, ideation, discussion, published, committed, abandoned). Each RFD lives on its own branch until published. Short URLs (42.rfd.oxide.computer), chat-bot fuzzy search, and an auto-maintained CSV index make them discoverable. Guidance: "3-5 business days to comment on your RFD before merging seems reasonable."^[14]

An RFC progresses through named states; the Send-Back path is the one most authors forget to plan for.

Amazon 6-pager, 2-pager, and PR/FAQ#

Amazon banned PowerPoint in favor of prose narratives. Jeff Bezos argued that full sentences force clearer thinking than bullet points, which can hide sloppy logic behind vague fragments.^[15]

The PR/FAQ starts with a mock press release (heading, subheading, problem, solution, customer quote, getting-started) followed by External FAQs (price, how it works) and Internal FAQs (TAM, competition, "top three reasons this product will not succeed"). That last question is the truth-seeking forcing function. Amazon spent over a year iterating the initial AWS PR/FAQ.^[16]

The 6-pager for strategic planning has six sections: introduction, goals, tenets, state of the business, lessons learned, and strategic priorities. Tenets use the "better than / worse than" framing: "We value speed of iteration over completeness of specification" forces the author to name what they sacrifice.

The meeting format: 15-20 minutes of silent reading at the start, then 40 minutes of discussion.^[16:1] Silent reading ensures every reviewer actually reads the doc, eliminating the "I skimmed the email" failure mode.

Company-Specific Flavors introduces Amazon's writing culture in the interview context. This chapter goes deeper on the mechanics.

Review culture and async norms#

The doc is only as good as its review. Three principles make review work:

1. Ask, don't tell. Frame feedback as questions to uncover author intent. Oxide's guidance: "if the comment you are about to make is not something you would want someone commenting on an RFD of yours, then do not make the comment."^[14:1]
2. Thread resolution belongs to the author. The author decides which comments to accept but must address every thread: agree, push back with reasoning, or escalate.
3. Time-box the review window. Rust uses 10 calendar days for FCP.^[10:1] Oxide suggests 3-5 business days.^[14:2] Without a deadline, docs stall indefinitely.

Uber's scaling lesson: at 2,000+ engineers, hundreds of RFCs per week overwhelmed senior reviewers. The fix was tiered templates (lightweight for team scope, heavyweight for org scope) and a purpose-built tool with search and approver tracking integrated into Phabricator.^[3:1]

The review phase is where the doc pays for itself; skipping or rubber-stamping it is the single most expensive engineering shortcut.

Doc output by engineering level#

Written output scales with scope. At L4, engineers execute specs and contribute component-level writeups. At L5, they drive team decisions through design docs and ADRs. At L6 (Staff), cross-team RFCs become the primary leverage and reviewing other engineers' docs is a core responsibility. At L7 (Principal), docs set multi-year architectural direction, often in Amazon 6-pager or strategy-doc form.

Doc output correlates with engineering level; L6 is the inflection where writing RFCs that span teams becomes the primary leverage.

Real-World Example#

Google's design-doc culture at scale

Google treats design docs as a precondition for coding, not a deliverable produced in parallel.^[1:5] A 2023 study analyzed 141,652 approved design documents authored by 41,030 users over four years.^[2:1] The findings:

• Typical length: 10-20 pages for major projects; 1-3 page "mini design docs" for incremental work.^[1:6]
• Failure modes: Unclear reviewer lists, ambiguous approval state, and stalled threads were systemic issues. Structured interventions (pre-populated metadata, automated reviewer assignment) reduced median time-to-approval by 25%.^[2:2]
• No single mandated template. The section list is cultural convention, not tool-enforced. Teams converge on similar structures because the problems are universal.^[1:7]
• Privacy and security reviews are mandatory gates for any project touching user data. A separate privacy design doc is required.^[1:8]
• Docs feed performance review. This creates a double-edged incentive: engineers write docs to demonstrate impact, but the incentive can produce docs that describe state rather than decisions.^[4:1]

The "US constitution with amendments" pattern is Google's acknowledged failure mode: rather than update the original design doc, teams link out to new "amendment" docs, creating an archaeology problem for future maintainers.^[1:9] The antidote is Nygard's immutability principle: accept that the original doc is a snapshot, and write new ADRs for subsequent decisions.

Trade-offs#

Common Pitfalls#

Exercise#

Write an ADR for "migrate from MongoDB to Postgres" using the Nygard template: Context, Decision, Status, Consequences. One page. Bonus: draft the superseding ADR you would write if, 18 months later, Postgres had become the bottleneck.

Key Takeaways#

• The design doc is the decision. Whiteboard sketches evaporate; written artifacts compound into institutional memory.
• ADRs are immutable. Never edit a past ADR; write a superseding one. The history is the value.
• Non-Goals and Alternatives Considered are the two sections that separate senior from junior writing. Spend the most time here.
• Match format to scope: ADR for team decisions, design doc for cross-team architecture, RFC for public commitment, 6-pager for executive alignment.
• Review culture matters more than template choice. Ask-don't-tell feedback, time-boxed windows, and thread resolution by the author make any format work.
• Doc output correlates with engineering level. At L6/Staff, writing RFCs that span teams becomes the primary leverage.
• Truth-seeking beats selling. A doc with only pros is a pitch deck, not an architecture decision.

Further Reading#

• Documenting Architecture Decisions (Nygard, 2011) - The original ADR essay; 1,200 words that changed how teams record decisions. Read this first.
• Design Docs at Google (Malte Ubl, 2020) - The most cited single source on modern design-doc practice; covers sections, anti-patterns, and review culture.
• RFD 1: Requests for Discussion (Oxide Computer, 2020) - One of the clearest modern RFC processes on the open web; includes tooling, states, and cultural norms.
• Engineering Planning with RFCs, Design Documents and ADRs (Gergely Orosz, 2022) - How Uber's doc process evolved from DUCK to tiered ERDs at 2,000+ engineers.
• Improving Design Reviews at Google (Ziftci and Greenberg, 2023) - Data-driven paper analyzing 141K design docs with concrete interventions that reduced approval latency by 25%.
• About MADR - The Markdown ADR template with rationale for each optional section; useful when Nygard feels too minimal.
• Working Backwards PR/FAQ Instructions and Template - Full template and meeting format from the authors of the Amazon book.
• rust-lang/rfcs README - Rust RFC process including the FCP mechanism and mandatory Drawbacks section.

Flashcards#

References#