Most design docs are unreadable, and the reason is not that they are too long. The reason is that they answer the wrong question.

The wrong question is what should we build. The right question is which option should we pick, and why. The wrong question turns the doc into a specification. The right question turns it into a decision artifact, and the difference is the difference between a doc that gets six approvals and a doc that gets six comments asking "have you considered X".

This article is the structure I now use for every design doc, the order I write the sections in (which is not the order they appear), and the four anti-patterns I have learned to avoid. The format works for one-pager RFCs and for ten-page architecture proposals; the structure scales, the length does not.

What an RFC actually is

An RFC ("Request for Comments") is a written argument for a specific decision. The author is making a recommendation. The reader's job is to evaluate the recommendation, not to receive a brief. If your doc does not contain a recommendation, it is not an RFC, it is a position paper or a discussion starter, and it should be labelled as such.

The corollary that a lot of new authors miss: a doc written as a neutral exploration of options is harder to review than a doc that picks a side. Neutrality sounds responsible. In practice, it pushes the decision-making cost onto the reviewer, who has to construct the recommendation themselves before they can agree or disagree. Pick a side in the doc, defend it, and let reviewers attack the defense. The reviews come back faster and the conversation is sharper.

The structure I use

Every RFC I write now has the same six sections in the same order. The whole doc is between 600 and 3,000 words. Anything longer is a sign that the doc is trying to be both an RFC and an implementation plan, and they should be split.

Section 1: TL;DR (3-5 sentences)

The first thing on the page. What problem we are solving, what I am proposing, why this proposal over the alternatives, and what the risk is. A reader who reads only the TL;DR should know enough to leave a useful comment.

The TL;DR is also the section I write last, after the rest of the doc has settled. Writing it first locks me into a position before I have actually thought about the alternatives.

Section 2: Context (the situation that forced this doc)

What is the world that this doc is responding to? Not the whole history of the system. Specifically: what changed recently or is about to change, that means the current approach no longer fits.

Context anti-pattern (avoid)
  "Our system has services A, B, and C. Service A talks to B over HTTP.
   Service B has a Postgres database. Service C runs on Lambda..."
   (this is a system tour, not a context section)

Context done well
  "Last quarter, B's request volume grew 8x. The Postgres CPU on B is
   pinned at 90% during business hours and we have already vertically
   scaled twice. We need a different read path before the next traffic
   step. This doc proposes that path."

The difference is that the second one tells me, in three sentences, why I am reading the doc. The first version makes me read four pages before I find out.

Section 3: Goals and non-goals

A bulleted list of what success looks like, and a parallel list of what is explicitly not part of this proposal.

The non-goals list is the section I added to my template after the third RFC where reviewers spent half the comment thread asking why I had not solved a problem I never intended to solve. "This RFC does not cover replacing the auth system" in the non-goals saves an hour of conversation about the auth system.

Keep this section short. Three to five goals, two to four non-goals.

Section 4: Options considered

This is the heart of the doc. For each plausible alternative I considered, including the one I am recommending, I write:

• A sentence describing what the option is
• A short paragraph on why it is appealing
• A short paragraph on the costs (engineering effort, operational risk, ongoing maintenance, blast radius if it goes wrong)
• A bulleted list of the trade-offs that distinguish this option from the others

I write at least three options, even if I think two of them are clearly worse than the third. The cost is one extra paragraph each. The benefit is large: the reviewer can see I considered the alternatives and why I am rejecting them, which short-circuits the "have you considered X" comments.

The options I write up are usually:

1. The one I am recommending
2. The most obvious alternative (often "do nothing" or "the simplest thing that could work")
3. The most ambitious alternative (often the one a more senior engineer might propose)

Section 5: Recommendation

The option I am picking, and why. This section is short (3-6 sentences) because the work was already done in section 4. The recommendation is the conclusion of the comparison, not a new argument.

The phrasing that has worked for me: "I recommend option B. The trade-off that decides it for me is X: option A is cheaper but does not address the read-path bottleneck, option C is more thorough but doubles the on-call surface area, option B costs the same as A and addresses the bottleneck within the existing on-call surface."

That sentence is doing real work. It names the trade-off, it concedes the strengths of the rejected options, and it explains the deciding factor. A reviewer who disagrees can attack any of those three claims directly.

Section 6: What we will do next

If this RFC is approved, what happens? Who owns the work, what is the rough timeline, what milestones gate the rollout, and what are the rollback criteria. Half a page.

This is not an implementation plan. It is the bridge from "decision approved" to "work scheduled". A reviewer should leave this section knowing the next concrete step, not a Gantt chart.

The four anti-patterns I have learned to avoid

Four shapes of doc that get written a lot, and that all fail to get the conversation moving.

The brief that hides as an RFC. A doc that describes the proposal in detail but never names the alternatives. The reader cannot evaluate the recommendation because there is nothing to compare it to. The fix: every RFC has at least three options in section 4, even if writing the second and third feels artificial.

The neutral survey. A doc that lists three options with their pros and cons but does not pick. As I said above, this offloads the decision to the reviewer. Pick a side. The doc gets sharper, and so does the discussion.

The code-snippet doc. An RFC that is mostly code samples ("here is what the new API will look like"). The code is fine in moderation but it is implementation, not decision. If the doc lives or dies on whether the API ergonomics are right, the doc is solving a different problem than the RFC is supposed to solve. Move the code into an appendix or a follow-up implementation plan.

The boil-the-ocean doc. A doc that tries to redesign the entire system, take the team to v2 of every service, and re-platform onto Kubernetes, all in one RFC. These are unreviewable; reviewers cannot agree to all of it and disagree with parts. Split into one RFC per decision. The decisions can reference each other but each one stands alone.

The reviewing side: what a useful comment looks like

I spend roughly as much time reviewing other people's RFCs as writing my own. The comments I find most useful, when I am the author, are the ones that engage with my reasoning rather than the ones that propose new options.

Useful comment shapes:

• "In option B, you say the cost is X. I think the cost is actually 2X because of Y. Does that change the recommendation?"
• "You did not list option D. What is the reason it is not in the running?"
• "The non-goal 'we will not change the auth system' makes me nervous because option B will need a small auth change. Can you call that out?"
• "Approved. Specifically, your point about X is what convinced me; if X is not true, I want to revisit."

Not-useful comment shapes:

• "Have you considered just using Kafka?" (no, but you have not said why)
• "This seems too ambitious." (specifically?)
• "+1" (does not record what convinced you, so the next reviewer learns nothing)

The culture I aim for, on the teams I lead, is that reviewers either engage with the reasoning, propose a specific alternative the author has not considered, or explicitly approve. "+1" without context is a sign that the reviewer did not read carefully, and I gently push back on it.

How long the doc should be

Someone always asks. The honest answer is "as short as it can be while answering the questions reviewers will have". For a one-team decision (e.g. "which job queue library to use") that is often 600-1000 words. For a cross-team decision (e.g. "how should we structure inter-service authentication") it is often 1500-2500. For a major architectural change (e.g. "how do we migrate to event-driven") it can be 3000+, and at that length I would consider splitting it into two or three docs.

The number of pages is not the goal. The goal is that an informed reviewer who has not seen the doc can read it once and leave a useful comment. If the doc is too short, the reviewer asks clarifying questions and the cycle stalls. If the doc is too long, the reviewer skims and the comment is shallow. Aim for the length where one careful read produces an actionable response.

Write the doc to be skimmed

The last thing I want to leave you with is a structural point about formatting. RFCs are read by people in a hurry. They are read by your tech lead between meetings, by your skip-level on a phone, by a senior engineer from another team who has 15 minutes before lunch. The doc has to survive the skim. Bold the key claims. Use bullet lists for the options. Use a short table for the trade-off comparison. Put the TL;DR at the very top. The doc that wins approvals is the one a busy reader can extract value from in five minutes and depth from in twenty. The structure above is built for exactly that, and it is the part of the format that has paid back the most over the years I have been writing RFCs in earnest.