Writing RFCs and Design Docs

Learning outcomes

You have a plan to split the monolith into two services. You know it is right. You write it up, post the link, and wait. A week later the document has two comments, both bikeshedding the service names, and the real decision is still unmade. Meanwhile a colleague proposed a smaller change the same week, got six reviewers to sign off in two days, and is already building it. The difference was not the quality of the idea. It was the quality of the document. This page is about writing the document that wins alignment instead of the one that stalls.

After studying this page, you can:

• Explain the three jobs an RFC does at once: propose a direction, win alignment from reviewers, and leave a durable record of why.
• Write the standard sections (summary, context, goals and non-goals, design, alternatives, risks, rollout, open questions) and say what each one is for.
• Lead with a summary a busy reviewer can read in thirty seconds, and draw scope with explicit non-goals.
• Frame a tradeoff so the reasoning is auditable: name the real alternatives, put their costs on one axis, state each failure mode, and give the decision rule.
• Write the alternatives-considered section that signals senior judgment, and anticipate objections before a reviewer raises them.
• Write for asynchronous review, ask for a clear decision, and choose between a heavyweight design doc and a lightweight ADR.

Before we dive in

Here is the problem that makes this whole genre necessary. A team is about to build something big: a new service, a data migration, a change to how every request is authenticated. The work will touch many people, take weeks, and be hard to undo. If the team just starts coding, three bad things happen. People who should have weighed in never get the chance, so an objection surfaces halfway through, when changing course is expensive. Nobody agreed on what success even means, so the work drifts. And a year later, when someone asks why it was built this way, the answer lives only in the heads of people who have since left.

The RFC, short for request for comments, is the answer to all three. It is a document you write before building, circulated so people can comment, that proposes a direction and captures the reasoning behind it. The same artifact goes by other names, design doc, technical spec, one-pager, but the function is identical: think in writing, in the open, before the cost of changing your mind goes up.

This is not the same skill as documenting a system after you build it, which is covered in technical documentation. That writing describes what exists. This writing argues for what should exist, to an audience who can still say no. The whole craft turns on that one fact: your reader is a decision-maker who has not yet decided, and your job is to help them decide well and fast.

Mental Model: three jobs in one document

The wrong model is that an RFC is a description of your plan: you have a design in your head, and the document writes it down so others can read it. Under that model, a good RFC is a complete and accurate spec, and the goal is coverage. This is the model that produces a forty-page wall of design detail that nobody approves, because it answers a question the reader was not asking.

The better model is that an RFC does three jobs at the same time, and a sentence that serves none of them is wasted. It must propose a direction, so the reader knows what you want to do. It must win alignment, so the people affected agree, or surface their disagreement now while it is cheap. And it must leave a record, so a future reader understands not just what was decided but why, and which other options were weighed and dropped. The same paragraph often does two of these at once: a well-framed tradeoff both persuades a current reviewer and explains the choice to a reader a year out.

Holding the three jobs in view changes what you write. The propose job demands a clear, specific design. The alignment job demands that you anticipate objections and ask for an actual decision, not just narrate. The record job demands that you write down the alternatives you rejected and why, which feels like wasted effort until the day someone re-proposes exactly the option you already ruled out.

Breaking it down

1. The standard structure, and why each part exists

RFCs converge on a standard set of sections not by fashion but because each one answers a question a reviewer will otherwise ask in a comment. Learn the sections as a list of pre-answered questions, and the structure stops feeling like a template you fill in and starts feeling like a conversation you are getting ahead of.

The table below is the backbone. Read the third column as the question each section heads off, and the fourth as what a careful reviewer actually checks when they reach it.

Two things about the order. The sections run roughly in the order a reviewer needs them: the problem before the design, because a solution makes no sense until you feel the problem, and the alternatives after the design, because you compare against the thing you just proposed. And the structure is a default, not a law. A small change may fold goals and design into one paragraph; a large one may split the design into several. The test is never “did I fill in every heading” but “did I pre-answer every question a reviewer would otherwise ask.”

2. The summary up top, because the reviewer is busy

The single highest-value paragraph in the document is the one at the very top, and it is the one writers most often skip. Your reviewers are senior, busy, and reading your doc between two meetings. Many of them will read only the summary and then either approve, skim for their area, or decide it does not need them. If the summary does not stand on its own, you have lost the readers you most needed.

A good summary states, in a few sentences, the problem, the proposed direction, and the decision you are asking for. It is not a teaser that withholds the answer to make you read on; it is the answer, with the rest of the document as the evidence. This is the inverted pyramid from the principles of clear prose: lead with the conclusion, because the skimmer may never reach the end. Watch the difference between a summary that hides the proposal and one that leads with it.

The strong version is not shorter by accident. It puts the load-bearing information, the proposal and the ask, where the reader looks first, and demotes the history to support. If a reviewer reads only those four sentences, they still have the one thing they needed.

3. Goals and non-goals: drawing the box

Goals say what success looks like. Non-goals say what you are deliberately not doing, and they are the more powerful of the two, precisely because they are the ones a writer is tempted to leave out. A non-goal does two jobs at once: it stops scope creep before it starts, and it heads off an objection before a reviewer raises it.

Suppose your proposal is to add a read-through cache to speed up the product page. Without non-goals, three different reviewers will each pull you somewhere else: one asks why you are not also caching the checkout flow, one worries this is a backdoor rewrite of the data layer, one wants to know your plan for cache invalidation across regions. Each is a reasonable question, and each can derail the thread for days. Now add a non-goals section: this does not touch checkout, does not change the data layer, and does not attempt cross-region invalidation, which is tracked separately. The same three reviewers read that, see their concern was anticipated, and move on. You did not duck the questions; you drew a box and said, on purpose, what is outside it.

4. Framing tradeoffs to persuade

This is the central senior skill, so it gets its own section. A decision is rarely between a good option and a bad one; it is between options that are each good on some axis and bad on another. The amateur move is to assert that your option is best. The senior move is to make the tradeoff legible, so the reader can see the choice the way you see it and arrive at your conclusion themselves. A reader who is shown the reasoning trusts the conclusion; a reader who is only handed the conclusion looks for the catch.

A tradeoff framing that persuades has four parts, and skipping any one of them weakens it. The flowchart lays them out as a sequence you can run on any decision.

Walk through why each part earns its place. Naming the real alternatives, including the one a skeptic would reach for, signals that you did the homework and removes the reviewer’s instinct to play devil’s advocate, because you already did. Putting costs on one shared axis, latency, or operational load, or migration weeks, lets the reader compare options directly instead of in incommensurable units. Stating each option’s failure mode is the most honest and most trusted move: an engineer who tells you exactly where their preferred design breaks has earned the benefit of the doubt everywhere else. The decision rule then makes the call explicit: you are choosing to pay this cost to avoid that worse one. And naming what would reverse the decision, the benchmark result, the traffic level, the team size, makes the whole thing auditable: a future reader can check whether the condition still holds. This deliberate, reason-on-the-table framing is the same discipline that governs a good design review, treated from the reviewer’s side in technical discussions and reviews.

5. Alternatives considered: the part that signals judgment

Of all the sections, alternatives considered is the one experienced reviewers read first to gauge whether the author is senior. A proposal with no alternatives reads as either naive, you did not know there were other options, or evasive, you knew and hid them. A proposal that fairly weighs two or three real alternatives reads as the work of someone who can be trusted with a big decision, because they have already argued both sides.

The craft is to make each alternative a fair fight, not a strawman. Describe each option as its advocate would, give its genuine advantage, and then state the specific reason it loses for this problem in this context. “We could shard the database; this gives us horizontal write scale, but our write volume is low and sharding would add operational complexity we do not need yet” is a fair rejection: it grants the upside and rejects it on a stated, checkable ground. Compare that to “we could shard, but that is too complex”, which dismisses without engaging and makes a reviewer suspect you never really considered it.

6. Writing for asynchronous review

An RFC is read without you in the room. Nobody is there to clarify, to answer the obvious question, to say “no, I meant the other thing.” The document has to carry the whole conversation alone, which puts three demands on how you write it.

Make it skimmable. A reviewer arrives with a goal, often a narrow one, the security person checks the auth model, the database owner checks the schema, and scans for their part. Descriptive headings, a summary up top, short paragraphs, and the key claim first in each one let a reader route themselves. A wall of undifferentiated text forces every reviewer to read everything, so most read nothing.

Anticipate and pre-empt objections in the doc. The questions a reviewer would ask in a comment should already be answered in the text, because a comment thread is slow: a question posted Monday gets your answer Tuesday and the follow-up Wednesday, and the decision slips a week. When you can feel an objection coming, “won’t this break the mobile clients?”, answer it in a sentence where it arises. Each pre-empted objection is a comment thread that never happens.

State the decision you are asking for, plainly, and put it where it cannot be missed. The most common way a doc stalls is that it never actually asks for anything: it describes a design, trails off, and leaves reviewers unsure whether they are being asked to approve, to brainstorm, or just to be informed. End with the explicit ask, “I am requesting approval to proceed with the token service; please comment by Friday”, so there is no doubt about what a reader is supposed to do.

7. ADRs and the document lifecycle

Not every decision deserves a full RFC. For a smaller, more local choice, which library, which naming convention, which of two reasonable patterns, the lightweight form is an architecture decision record, or ADR: a short note, often a single page, capturing the context, the decision, and the consequences. An ADR does the record job of an RFC without the heavy propose-and-align machinery, and it is the right tool when the decision is real but the blast radius is small. The instinct to match the document’s weight to the decision’s weight is itself a mark of judgment: a five-line ADR for a five-minute decision, a full RFC for a quarter of work.

Whichever form you use, the document has a lifecycle, and knowing where a doc sits in it tells everyone how to treat it. The states run from draft to a recorded decision.

The loop in the middle, between commenting and revising, is the heart of the genre and the reason it is called a request for comments: the document is meant to change as reviewers push on it. A doc that reaches the decided state has done all three jobs, it proposed, it aligned the people who commented, and now it stands as the record of why the call was made. That final record is the part with the longest life: long after the work ships, the doc answers the question a new engineer will eventually ask, “why is it built this way, and did anyone consider the obvious alternative?”

Common mistakes

Each mistake below is a way of forgetting that your reader is a busy decision-maker who has not yet decided.

No summary, so the proposal is buried. The reviewer opens the doc, finds three paragraphs of history, and bounces before reaching the point. Lead with a summary that states the problem, the proposed direction, and the ask, so a reader who stops after it still has the decision.

No alternatives considered, so the proposal reads as naive or evasive. A single option with no comparison gives the reviewer nothing to check your judgment against, and senior readers distrust it on sight. Weigh two or three real alternatives, each granted its genuine strength before you reject it on a stated ground.

No non-goals, so scope creeps and objections multiply. Without an explicit boundary, every reviewer pulls the doc toward their own concern, and the thread sprawls. Name what you are deliberately not doing; each non-goal is an objection you answer in advance.

Not anticipating objections, so the comment thread does the work the doc should have done. Every question a reviewer asks in a comment is one you could have answered in the text in a fraction of the time. Imagine the loudest reviewer and pre-empt them on the page.

No clear decision requested, so the doc stalls. A proposal that describes but never asks leaves reviewers unsure what to do, and they default to doing nothing. Close with the explicit ask and a deadline.

A wall of text with no structure, so a skimming reviewer cannot find their part. Asynchronous review depends on a reader routing themselves to the section they care about. Descriptive headings, short paragraphs, and the point first make a long doc usable; a single dense block makes it invisible.

Mastery Questions