Prompt Notebook

Design doc · RFC · Engineering

How to write a design doc, with a filled-in example

By T. Krause

A design doc sets out a technical proposal, the alternatives and the trade-offs before anyone builds. Here is when to skip one, what each heading has to answer, how to run the review so it ends in a decision, and an invented example with its comment threads.

To write a design doc, describe the problem and its facts, propose one design, show the alternatives you rejected and why, then list the risks, a rollout plan and any open questions. Add a comment deadline and the name of the person who decides, and share it before the build starts. The doc is worth writing when more than one approach could work and a mistake would be expensive to undo.

Many teams call the same document an RFC, for request for comments. This guide goes through what a reviewer needs from each heading and how to stop a review from dragging on. It ends with an invented example, including the comment threads that changed it. If you'd rather start from a page with the headings in place, copy our free design doc template.

When to skip the design doc

Malte Ubl's article Design Docs at Google is blunt: "Writing design docs is overhead." He puts the decision on one question, whether the solution is ambiguous, and adds: "If it is not, then there is little value in going through the process of writing a doc."

His warning sign is a doc that reads like an implementation manual. If it says how you'll build something "without going into trade-offs, alternatives, and explaining decision making", he writes, you probably should have written the program instead.

In practice, we'd sort the work like this. The table is our own rule of thumb, not Ubl's.

SituationWhat to write
One obvious fix, easy to reverseA ticket, and a good pull request description
Two real options, and only one part of the system affectedA one-page doc, or a line in your decision log
Several teams or services affected, or hard to undoA full design doc
You're asking whether to build it at allA project brief first
You're defining what the feature must do for usersA PRD first, then the design doc for how you'll build it

Length follows the same logic. Ubl writes: "The sweet spot for a larger project seems to be around 10-20ish pages." He adds that a "1-3 page 'mini design doc'" helps with incremental improvements. For a small team, the short version is the common case.

What each heading has to answer

Ubl's first rule on format is "Write them in whatever form makes the most sense for the particular project", and our template is one reasonable arrangement. A reviewer opens a design doc with a handful of questions in mind, and each heading answers one of them.

Status callout: what do you want from me, and by when? Give the comment deadline, the author and the person who decides. Put this at the very top. The deadline and the named decider are our own additions to the usual advice, and they give the review an end.

Summary: what are you proposing? Three sentences at most, naming the design, and written last. A busy reader should be able to stop here and know whether the doc concerns them.

Context: what's true today? Facts with numbers, such as the current cost, how often something fails or how much data you hold. Ubl says this section "should be entirely focused on objective background facts". Link to detail and leave your preferred solution out of it, because a reader who doubts your facts won't trust your design.

Ubl also recommends a list of goals and non-goals. Non-goals, in his words, are "things that could reasonably be goals, but are explicitly chosen not to be goals". Our template has no separate heading for these, so add a Non-goals line under Context, as the example below does. That line can settle a review argument before it begins.

Proposal: what exactly would you build? Start with an overview, then the details that reviewers need to judge it. Ubl's advice is to focus on trade-offs, and to "show why a particular solution best satisfies those goals".

Alternatives considered: what else did you look at? The next section covers this one.

Risks: what could go wrong, and how would you know? A useful risk has a consequence and a response, so "data migration is risky" isn't one yet. Ubl also tells authors to think about cross-cutting concerns, naming observability, security and privacy. If one of them matters here, this is a good place to say so.

Rollout: how do you get there without betting everything on one day? Numbered steps, each one reversible if you can manage it, with what you'll check before moving on.

Open questions: what don't you know yet? Be honest here. Mark any question that must be settled before the decision, and move the rest to a named person with a date.

Alternatives are where reviewers look hardest

Ubl calls this section "one of the most important ones", because it "shows very explicitly why the selected solution is the best given the project goals". Reviewers will think of other options anyway. If yours aren't on the page, the comments will fill up with them.

Three habits make this section work. They're ours, so weigh them against your team's experience.

  • Include doing nothing. It sets the baseline. If doing nothing is acceptable for another six months, the doc may be premature.
  • Compare on the same criteria. Take the two or three things your goals care about, such as cost, effort or failure behaviour, and score every option on those. A small table works well.
  • Write the rejected option as its fans would. If a colleague prefers it, ask them to check your description. An alternative written to lose teaches nobody anything, and its supporters will reopen the argument later.

How much code belongs in it

Less than most engineers first write. Ubl says design docs "should rarely contain code, or pseudo-code except in situations where novel algorithms are described", and warns against pasting complete schema or interface definitions, which are verbose and go stale fast.

We'd draw the line at the snippet the decision depends on. Our template's sample includes one short search query, because the ranking is what its reviewers need to judge, and the example below shows the one statement that its design relies on. Anything longer can sit in a linked prototype. Ubl gives prototypes a good word too: "'I tried it out and it works' is one of the best arguments for choosing a design."

Run the review so that it ends

Ubl describes a range of reviews, from sending the doc to a team list, with discussion in comment threads, to formal review meetings. He also calls reviews "a dangerous trap of overhead". For a small team, the light version is usually enough.

  1. Share it early with one or two people who know the area, and fix the obvious problems.
  2. Send it to everyone affected, with the deadline in the callout. We'd start with a week, and adjust it to your team.
  3. Answer each comment in the thread, and change the doc when a comment changes your mind. The doc should show the current thinking.
  4. On the deadline, the decider decides, and writes down the reasons. An open question that doesn't block the decision goes to a named person.
  5. Update the status callout, and add a row to your decision log that links to the doc.

Some teams formalise step 5 further. Oxide Computer's public RFD 1 gives every document one of six named states, from prediscussion to committed or abandoned, so anyone can see where it stands. A small team can get most of that from one line in the callout.

After the decision

The doc will be wrong somewhere, because building teaches you things. Ubl's rule of thumb is "If the designed system hasn't shipped yet, then definitely update the doc." He admits that "we humans are bad at updating documents", and says links from the original to any later documents help the next person.

He also suggests re-reading your own design docs "a year or 2 later" and asking what you got right and wrong. Put a reminder in your calendar on the day you close the doc.

A filled-in example: invoice PDFs in the background

Everything below is invented: the company, the people, the numbers and the dates. Sparrowbill is a small invoicing app. The doc uses the headings of our template, with a Non-goals line added under Context. It's shown as it stood after the comment threads that follow it.

RFC 021. Open for comments until Friday 13 November 2026. Author: Nadia Osei. Decision by: Joel Brandt.

Summary

Generate invoice PDFs in a background job table in Postgres, with three workers, and stop generating them inside the web request. Large batches stop timing out, and we add no new service to run.

Context

  • Each PDF takes about 3 seconds to generate, and a web request times out after 30 seconds, so a batch of more than 10 invoices fails
  • 40 accounts send more than 10 invoices at once, mostly on the first of the month
  • About 2,400 invoices go out in the hour after 09:00 on the first of each month
  • Non-goals: faster PDF rendering, and changing the PDF layout

Proposal

  • A new pdf_jobs table, with one row per invoice per send
  • Clicking Send creates the rows and returns straight away. The batch screen shows "Sending"
  • Three workers take one job at a time. At 3 seconds a job, three workers clear 2,400 invoices in 40 minutes

The one statement reviewers need to check is how a worker claims a job:

update pdf_jobs set status = 'running', started_at = now()
where id = (
  select id from pdf_jobs
  where status = 'queued'
  order by created_at
  limit 1
  for update skip locked
)
returning id, invoice_id;

Alternatives considered

OptionNew service to runSurvives a deploy mid-batchEffortResult
Do nothingNoNoNoneRejected. Those 40 accounts keep failing each month
Raise the request timeoutNoNoOne dayRejected. A long request still dies on a deploy, and it ties up a web server while it runs
Hosted queue serviceYesYesOne weekRejected for now. Works well, but adds a bill and a second place to look when something fails
Job table in Postgres (proposal)NoYesOne weekChosen

Risks

  • A worker dies mid-job and the customer gets the invoice twice. The worker sends each email with an idempotency key built from the invoice and send ID, so the mail provider drops a repeat. A job stuck in running for 5 minutes goes back in the queue, up to three attempts
  • Workers use database connections at the busiest time of the month. Check connection use during step 2 of the rollout
  • If volume grows far beyond today's, the table stops being the simple option. Reopen this decision if we pass 20,000 jobs a month

Rollout

  1. Build the table and workers behind a flag, on our own test account, by Friday 27 November
  2. Use the new path for the 40 large accounts on the 1 December run, and leave everyone else on the old path
  3. Move all accounts for the January run if step 2 had no duplicate sends
  4. Remove the old path after the February run

Open questions

  • Do customers need a progress bar on the batch screen, or is "Sending" enough? Owner: Nadia, by Friday 27 November

What the comment threads changed

The first version of the doc had neither an idempotency key nor a volume limit. Here's what happened in the review, also invented.

Marek, on Risks: "What happens if a worker dies after sending the email but before marking the job done?" Nadia had only planned to retry the job, which would have sent a second invoice. She added the idempotency key and the 5-minute rule. This was the most useful comment of the review, and it came from someone who had once debugged double emails.

Ines, on Alternatives: "A hosted queue gets us retries for free. Why write them ourselves?" Nadia asked Ines to check the description of that option, and Ines rewrote the first half of it. The team still preferred one less service at the current volume. Joel asked for the 20,000 line in Risks, so the rejection comes with a condition for looking again.

Ines, on Proposal: "Should the batch screen show progress?" Nobody knew what customers expected, and the answer didn't affect the design. Joel moved it to Open questions with an owner, and the review carried on without it.

On Friday 13 November, Joel approved the doc, changed the callout to "Approved" and added one row to the decision log: "Invoice PDFs move to a Postgres job table. Hosted queue rejected for now, reopen above 20,000 jobs a month." If the 1 December run sends anyone a duplicate, step 3 of the rollout doesn't go ahead.

Writing a design doc in Prompt Notebook

Prompt Notebook is ours, so read this part with that in mind. The design doc template is a single page with a status callout, a code block holding one search query, and each rejected alternative in its own toggle. The sample is an invented proposal for moving search to Postgres.

To collect comments, open Share and set the link to "Signed-in visitors can comment; others get view access". Reviewers sign in to comment. Comments appear in a panel beside the page. Page history shows what changed during the review, which helps when someone asks whether you took their point on board.

Once it's decided, add a row to your decision log and type @ inside it to link the doc. Ask your workspace can help when someone asks "have we looked at hosted queues before?". It reads at most eight matching pages per question and cites the ones it used, so check the linked page before relying on the answer. Ask AI on a selection takes typed instructions, such as "list the strongest objection to each of these alternatives", which is a useful check before you send the doc out. Treat what it returns as prompts for your own thinking, since it doesn't know your system.

Frequently asked questions

What is the difference between a design doc and an RFC?

Usually only the name. Both describe a proposed design and ask for comments before it's built. Some companies use RFC for a more formal process with numbered documents and named states. Use whichever word your team already uses.

What is the difference between a design doc and a PRD?

A PRD says what the product should do and why users need it. A design doc says how engineering will build it and which technical alternatives it rejected. They have different readers and change for different reasons, so keep them separate. Our PRD guide covers the other half.

How long should a design doc be?

As short as the decision allows. Malte Ubl's article suggests 10 to 20 pages for a larger project and 1 to 3 pages for incremental work. Most small-team decisions fit the short form. If yours keeps growing, split the problem into smaller ones.

Who should review a design doc?

Anyone who will build it, operate it or be affected by it, and at least one person who knows the area well. Name one person who decides. Everyone else advises, so the review can finish even when opinions differ.

Should you update a design doc after it's approved?

Yes, until the system ships. When the build shows that part of the design was wrong, change the doc and note why. After launch, link any later changes from the original, so the next person can find out what's still true.

Try it on your own notes

Prompt Notebook is free, with unlimited pages. Type one sentence and the AI drafts the first version.

Cookies and storage

Prompt Notebook needs one cookie to keep you signed in. Accepting turns on Google Analytics and Google's reCAPTCHA spam check on the contact form, and declining keeps the form working. Nothing optional runs until you choose.

Read the privacy notice