An RFC — request for comments, a term borrowed from the internet standards process and adopted widely across software organizations — is a written document proposing a significant technical decision, circulated for review and discussion before the decision is implemented. The format exists to solve a specific, recurring problem: significant technical decisions are often made informally, in a conversation or a chat thread, in a way that's hard for people not present at the time to meaningfully weigh in on, and hard for anyone to reference accurately later once the reasoning has faded from memory. The long-running public model for technical proposals is the RFC Editor.
Why the writing itself is doing real work
The discipline of writing a clear RFC forces a kind of thinking that an informal conversation doesn't reliably produce: articulating the actual problem being solved, not just the proposed solution; naming the alternatives that were considered and explaining specifically why they were rejected, not just presenting the chosen approach as though it were the only option; and being explicit about trade-offs and open questions, rather than presenting a decision as more settled and risk-free than it actually is. A proposal that can't survive being written down this clearly — where the reasoning falls apart once it has to be stated explicitly rather than gestured at in conversation — was probably worth catching before implementation began, not after. Rules that look simple can have detailed calculation consequences; the source provides a payroll example.
This connects to a general pattern that shows up elsewhere on this shelf as well, in the domain-driven-design guide's discussion of ubiquitous language: the act of writing something down precisely, in language other people can evaluate, tends to surface gaps and inconsistencies that stay comfortably hidden in looser, verbal discussion, where an audience's nodding along can be mistaken for actual, informed agreement.
What makes an RFC actually reviewable
An RFC that's genuinely useful for review tends to share a few specific properties: it's scoped to a single, coherent decision rather than bundling several unrelated proposals together, which makes focused feedback on any one of them harder to give; it states the problem before the proposed solution, so a reviewer can independently evaluate whether the proposed approach actually addresses the stated problem, rather than only being able to react to the solution in isolation; and it includes genuine alternatives that were seriously considered, not straw-man options included only to make the chosen approach look better by comparison.
- Scope an RFC to one coherent decision — bundling several unrelated proposals into one document makes focused, specific feedback on any single part much harder to give.
- State the problem clearly before presenting the proposed solution, so reviewers can independently judge whether the solution actually fits the stated problem.
- Include genuine alternatives that were seriously considered, with honest reasons for rejecting them — not token options included only to flatter the preferred choice by comparison.
- Be explicit about open questions and genuine trade-offs rather than presenting the decision as more settled or risk-free than it actually is — reviewers can't usefully weigh in on uncertainty that's been hidden from them.
Why this matters more for some decisions than others
Not every technical decision warrants an RFC — the format has a real cost in time, both to write and to review, and applying it to every small decision produces the same kind of process overhead that mandatory, universal code review of trivial changes can produce. RFCs earn their cost specifically for decisions that are expensive to reverse once implemented, that affect multiple teams or a wide surface of a system, or where genuine, substantive disagreement exists that a quick conversation hasn't resolved — the format is a tool for exactly those higher-stakes cases, not a universal step for every choice a team makes.
Read alongside the postmortem guide discussed elsewhere on this shelf, RFCs and postmortems are, in a sense, mirror-image writing disciplines — one making a decision's reasoning legible before it's implemented, when problems are cheap to catch; the other making a failure's causes legible after the fact, when the goal shifts from prevention to honest, blameless understanding.