Writing Technical RFCs That People Actually Read

The RFC Problem

Most engineering teams that adopt RFCs go through the same arc.

First, excitement: "We'll write proposals before building things! Alignment! No more surprise architectures!"

Six months later: nobody reads the RFCs. Decisions happen in Slack. The RFC is written after the fact as documentation. The system has collapsed.

The problem isn't the idea of RFCs. It's that most RFCs are written for the author, not the reader.

What an RFC Is Actually For

An RFC is not documentation. It's a decision-making artifact. Its job is to:

1. Ensure the right people have the information they need to weigh in
2. Surface objections before work begins, not during code review
3. Create a record of why a decision was made

If your RFC isn't doing all three, it's not working.

The Structure That Works

One-sentence summary. The first sentence should tell a busy engineer everything they need to know. "We're replacing our Redis-based session store with database-backed sessions to eliminate a single point of failure."

Context. What's the current situation? What problem are we solving? Why now? This section is for people who aren't close to the problem. Don't assume knowledge.

Proposal. What specifically are you proposing? Be concrete. Include code snippets, diagrams, and API shapes. Vague proposals get vague feedback.

Alternatives considered. This is the section most RFCs skip and shouldn't. Listing alternatives you rejected (and why) dramatically reduces back-and-forth in comments. Reviewers who would have suggested Option B see that you already considered it.

Risks and open questions. Be honest about what could go wrong and what you don't know yet. An RFC that pretends to have all the answers invites skepticism. One that names its uncertainties invites collaboration.

Decision criteria. How will you know this proposal is working? What would make you reverse it?

The Habits That Kill Engagement

Too long. If your RFC is over 1,500 words, cut it. Every extra word is a reason not to read it. Split scope if necessary.

Too academic. An RFC isn't a research paper. Use plain English. Active voice. Short paragraphs.

Buried ask. The reviewer shouldn't have to reach paragraph 8 to understand what you want from them. State it upfront: "I'm looking for feedback on the data model in Section 3 by Friday."

Written after the decision. If you write an RFC when the implementation is already done, you're not asking for input. You're asking for rubber stamps. People can tell. They stop engaging.

Getting the Review You Need

An RFC sent to the entire engineering org will be read by no one. Tag the two or three people whose input actually matters. Give them a specific deadline and a specific question.

"Can you review this by Thursday and let me know if the migration plan in Section 4 is feasible?" gets a response. "Feedback welcome" does not.

The Meta-Point

A good RFC makes the author look less smart and more trustworthy. It says: I've thought through the alternatives, I know the risks, I want your input before I commit to a direction.

That's the document that gets read. That's the process that produces better decisions.