Design docs, RFCs and ADRs at scale

Write it when the choice is hard. Show the trade-offs. Close it on a date, with one decider, and keep the call as an ADR.

Before you read: predict

A chat team's draft RFC, "Pin messages in a group", runs six pages: the new pinned_at column, the two endpoints, the migration's steps and the three screens that change. It names no other way to build the feature, and nobody on the team, or in the two teams it was shown to, has suggested one.

Before anyone builds it, what should happen to the draft?

The 30-second version

A design doc, or RFC, weighs a hard choice in writing before the code: the facts, the goals, the design with its trade-offs and the designs that lost. Write one only when the answer is in doubt. Across time zones, give it a closing date every team can use and one person who decides; record the call as an ADR.

Write it when the choice is hard. Show the trade-offs. Close it on a date, with one decider, and keep the call as an ADR.

How it works

Step 1 of 14

Before the code. A design doc is written before building: the high-level strategy and the key decisions, with the trade-offs weighed.

In the kitchen

a change to the house style goes out as a written proposal before any entry changes → a design doc before the code (step 1)

Analogy: A dictionary's house style across three offices

A dictionary is published in British, Canadian and Australian editions, with editors in London, Toronto and Sydney.

In the dictionary	In design docs
a change to the house style goes out as a written proposal before any entry changes	a design doc before the code (step 1)
the proposal sets its rule beside the rules weighed against it	trade-offs and the designs that lost (steps 2, 7)
one more headword the style guide already covers goes straight in	no doc where nothing is in doubt (step 3)
a forty-page proposal, half of it pasted word lists, goes unread	short, in rough form (steps 6, 9)
the proposal reaches all three offices with a closing date each can work to in its own hours	the comment window (step 12)
the editor-in-chief named on its first page rules on that date	the decider (step 12)
her ruling goes into the style register as one dated line	the ADR (step 14)

Breaks down when: a style rule costs nothing until the next print run; a software design starts costing as soon as code is built on it.

Contrasting case: a house style set by whoever edits last: no proposals, no closing date, and the three editions drift apart.

In real terms: write the doc when the choice is hard, close it on a date with one decider, and keep the call as an ADR.

What the sources support. Steps 1–11 and 13 are Ubl's account of Google's practice (2020, read 2026-10-15). Steps 12 and 14 are the row's practice advice: no item keys on them as cited; the window items are arithmetic.

Try it

Answer first, then check. Nothing is saved.

Question 1 of 8

A video-streaming company's platform team lists five proposals for next quarter. Its last two launches went out without the logging and privacy checks they needed. (1) Choose how the player picks a bitrate on phone networks: two approaches are on the table, nobody yet knows which copes better, the mobile and TV teams disagree, and the principal engineer, who reviews no code, wants a say; 8 weeks. (2) Upgrade the transcoder's library from 6.1 to 6.2, following the vendor's upgrade notes; 2 days. (3) Move subtitle files off a 2015 service whose design nobody wrote down, onto the object store every other service uses, the one way anyone has suggested; 3 weeks. (4) Rebuild the admin console's 40 screens in the company's component library, with no open design questions; 12 weeks. (5) Decide how watch history syncs across devices: three designs are on the table, and the data team and the app teams disagree about where it is stored; 6 weeks. The team writes a design doc only for the proposals that call for one, counted as the pack's model reads Ubl's test.

How many design docs will it write?

Question 2 of 8

A chat company's RFC on message retention goes to three teams: Berlin (the author's), San Francisco and Singapore. Each team works 09:00–17:00 local time, Monday to Friday. The author posts it on Monday 16 November 2026 at 08:30 Berlin time. The decider wants each team to get at least five full working days inside the comment window, a full day being the team's whole 09:00–17:00.

What is the earliest closing time, in Berlin time, that does it?

Question 3 of 8

A ticketing team's RFC proposes holding seats as rows in its Postgres database, each with an expiry time. Its goals: no seat is sold twice; a hold is released within a minute of expiring; nothing new to run this quarter. Three entries are drafted for its Alternatives considered section.

Which one belongs there?

Question 4 of 8

A payments-ledger team's RFC for hourly settlement has grown to 31 pages: context and scope 3, goals and non-goals 1, the design 8, the settlement API's whole OpenAPI file 9, the SQL that creates its four new tables 4, the batch job's source file 3, alternatives considered 2, and security, privacy and observability 1. The batch job reads each hour's payments and posts them in order, as every batch job in the ledger does. The reviewers ask for everything a design doc should leave out to go, judged as the pack's model reads Ubl's advice.

How many pages will be left?

Question 5 of 8

A video-streaming company's RFC on download limits goes to three teams: London (the author's), New York and Bangalore. Each team works 09:00–17:00 local time, Monday to Friday; the New York office is closed on Friday 4 December for its move, and the Bangalore office is closed on Wednesday 2 December for a staff training day. The author posts it on Wednesday 2 December 2026 at 13:00 London time, and the comment window closes on Wednesday 9 December at 17:00 London time.

Counting a full working day as a team's whole 09:00–17:00 inside the window, which team gets the fewest?

Question 6 of 8

A payments-ledger team's RFC moves settlement to hourly batches. Whether the design works rests on how the posting table's row locks behave under the new batches, which only one engineer, on another team, knows well. The architecture review meeting's next free slot is in five weeks.

What should the author do?

Question 7 of 8

In an interview you say your ticketing team's RFCs are reviewed before anyone builds. The interviewer adds a case: halfway through building, you find that the approved design's single queue can't keep each event's seat holds in order, so you switch to one queue partition per event. Nothing has shipped yet.

Which answer to "What happens to the RFC?" survives the interviewer's next question?

Question 8 of 8

A chat company's RFC adds search across all of a user's conversations, copying message text into a new search cluster. The company's privacy team has written its own privacy design doc for the feature, which goes through the company's privacy review; that review is due before launch, four months away.

What should the RFC's privacy part do?

Go deeper

Pro tips

Put the closing time, with its time zone and each team's local equivalent, and the decider's name in the RFC's first lines. When: the row's typical question "How do you make a technical decision across three teams in different time zones?" (step 12). Verify:
```
tip RFC-031 header · v1: Closes: (none) · Decider: (none) · v2: Closes: Tuesday 10 November, 17:00 Dublin (Tuesday 10 November, 12:00 Toronto, Wednesday 11 November, 01:00 Manila) · Decider: platform lead
```
Status: RAN.

Source

quote-check.mjs finds every passage below verbatim in its saved text. Valid as of 2026-10-15.

Malte Ubl, "Design Docs at Google" (industrialempathy.com, published 6 July 2020): https://www.industrialempathy.com/posts/design-docs-at-google/ (ubl-design-docs-at-google.txt). The row's first source; the saved text also holds the page's reader comments, which key nothing. The page supports steps 1–11 and 13 and the newcomer clause of step 14, and states every rule the model lib/docs.mjs encodes. Passages that decide a practice question are shown with that question's feedback, not here. Quoted: "The design doc documents the high level implementation strategy and key design decisions with emphasis on the trade-offs that were considered during those decisions." · "This section should be entirely focused on objective background facts." · "the design doc is the place to suggest solutions and show why a particular solution best satisfies those goals." · "one should withstand the temptation to copy-paste formal interface or data definitions into the doc as these are often verbose, contain unnecessary detail and quickly get out of date." · "copy-pasting complete schema definitions should be avoided." · "this section is one of the most important ones" · "Teams should standardize what these concerns are in their case." · "The sweet spot for a larger project seems to be around 10-20ish pages." · "it is absolutely possible to write a 1-3 page “mini design doc”." · "When things have progressed sufficiently to have confidence that further reviews are unlikely to require major changes to the design, it is time to begin implementation." · "When Google engineers get confronted with a system that they hadn’t previously touched their first question often is “Where is the design doc?”." · "Are you unsure about the right software design, and would it make sense to spend upfront time to gain certainty?" · "Relatedly, would it help to involve senior engineers, who might not be able to review every code-change, in the design?" · "Is the software design ambiguous or even contentious such that achieving organizational consensus around it would be valuable?" · "Does my team sometimes forget to consider privacy, security, logging or other cross-cutting concerns in the design?" · "Is there a strong need for documents that provide high-level insights into the design of legacy systems in the organization?" · "If you answer yes to 3 or more of these questions, then a design doc is probably a great method to start your next software project."
Michael Nygard, "Documenting Architecture Decisions" (Cognitect, 15 November 2011): https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions (nygard-documenting-adrs.txt). The row's second source and the source of the prerequisite arch-adrs, which owns the ADR's form, statuses and supersession; no step or item here keys on it.

Checked against the tools and docs as of 2026-10-15.

Predict first