← Blog

How to write RFCs your team actually reads

Start with the decision, split the plan into small slices, and understand every line, even when an AI agent writes the first draft.

An RFC is a product. Your teammates are its users, and they pay for it with their attention.

I've written a lot of RFCs over the years. The ones that worked weren't the longest or the most detailed. They were the ones someone could open between two meetings, understand what was being decided, and leave a comment that helped move it forward.

Hear it from me · 0:51

Why I wrote this one

Here's what I've learned. I also added a few interactive questions along the way. Have fun!

Say the decision first

Many RFCs start slowly: the history of the system, why it matters, what the document will cover. By the time the proposal appears, the reader is already tired.

Be direct. The first paragraph should say what you want to do, why, and what you need from the reader. If someone reads only that paragraph, they should still be able to tell you if they agree.

A manager at a previous company once gave me feedback on a doc by pointing me to a habit from the military: BLUF, short for bottom line up front. It comes from the US Army's writing rules, which ask you to put the main point at the very start. The reader might be busy, interrupted, or about to make a decision with only one minute to read. So the most important thing goes first.

That's the shape I want for an RFC:

  • The bottom line: what you want to do, and what you need from the reader.
  • The reasons: why this, why now, and why not the obvious other option.
  • The evidence: data, history, other options, and the detailed plan, lower in the doc or in an appendix.

Your reader has

Warm-up first

Webhooks are an important part of our platform, and our customers need them to be reliable.

In 2023 we moved webhooks out of the monolith into a separate worker, originally built for batch email, with a Redis-backed queue and a retry cron…

We propose retrying failed webhooks for 24 hours with backoff. We need a decision on the window by Friday.

They leave knowing that webhooks matter.

Bottom line up front

We want to retry failed webhooks for 24 hours with backoff. We need a decision on the window by Friday.

Failed deliveries are our top support ticket, most customer outages last under 6 hours, and the queue we already run supports backoff.

Ticket counts by month, outage durations from last quarter, the alternatives we considered, and the rollout slices…

They leave knowing what you want, and by when.

Same RFC, same facts, different order.

The warm-up version isn't wrong, and it has the same facts. It just makes the reader search for the point. Here's the same idea in a single paragraph.

Pick one

Two RFCs arrive in your inbox. Which first paragraph tells you what's being decided?

Which one would you rather get?

Being direct also applies to each sentence. Write "we will" instead of "it may be worth considering". And when you're not sure yet, say that directly too: "I don't know which one is better, and here's how we'll find out."

Write for someone new to the problem

You've been thinking about this problem for weeks. Your readers haven't. Some of them are on another team, some joined last month, and some will find the doc a year from now while trying to understand why the code works the way it does.

It's easy to try to fix that by adding everything. But context has a cost too. Every paragraph of background is something the reader has to keep in mind before they get to the part that matters. Give them enough to follow the proposal, and link to the rest.

Pick one

An engineer from another team opens your RFC. Which background helps them more?

Which one would you rather get?

What works for me: I write the background for a smart engineer who joined last week. If they would need to ask me a question to understand it, I add a sentence. If they would skip over it, it goes to an appendix.

Split the plan into slices

A plan with one giant step is hard to review, because the only possible answer is yes or no to all of it. It's also hard to ship, because nothing is released until everything is done.

Split the plan into slices: small steps that each ship on their own. Each slice should be useful by itself and safe to stop after. That gives reviewers something they can agree on today. It also gives you natural points to learn something and change the plan.

Pick one

Which plan would you rather review?

Which one would you rather get?

Slices also make the RFC easier to write. When I can't describe the first slice in one sentence, it usually means I don't understand the problem well enough yet.

Don't waste your open questions

The open questions section can be the most valuable part of an RFC. But it often becomes a place for everything: questions you could answer yourself, a discussion about names, and a "thoughts?" at the end.

Every question you add asks for someone's time. Use it on what really matters: decisions that are hard to undo, trade-offs you can't decide alone, and topics where someone else knows more than you. Say which answer you prefer, and who you think can answer.

Pick one

Which open questions are worth the reader's time?

Which one would you rather get?

Writing RFCs with AI agents

You can usually tell: every section is filled in, every option is listed, every risk has a plan, and the whole thing is three times longer than it needs to be.

I'm not against it. I actually recommend it. An agent can turn messy notes, a Slack thread, and a few links to the code into a structured first draft in minutes, and that speed is real. You don't have to start from an empty page, and it often finds gaps you hadn't thought about.

But the agent doesn't know what your team already knows, what they care about, or which of its twelve sections really matters. It tries to cover everything, and your reader needs focus. When you share a draft you don't fully understand, the work moves to the reviewers. Now ten people each spend twenty minutes trying to figure out what you meant.

Pick one

An agent wrote your RFC in ten minutes. It's twelve pages long, and every section is filled in. What do you do?

Which one would you rather get?

So spend at least an hour with the draft before anyone else sees it. Read it from start to finish. Rewrite the important parts in your own words. Remove anything you can't explain. My test is simple: if a teammate asks me about any line in the doc, I should be able to answer without opening it.

Not everything needs an RFC

RFCs should bring value to your team. Each one asks people to stop, read, and think about something new. That's worth it when the decision is hard to undo, or when more than one person needs to agree on it. Otherwise, it isn't.

When a team gets four RFCs in a week about things that could have been a PR description, people stop reading carefully.

Sort them

Does it need an RFC, or is a message enough?

  • Rename an internal helper used in three files
  • Change the shape of a public API response
  • Update a dependency to a new minor version
  • Move webhook delivery to a different queue provider
  • Add a filter to an internal admin page
  • Change when customers receive retried webhooks
0 of 6 sorted.

My simple rule: write an RFC when the decision is hard to undo, when it affects people outside your team, or when you really need other people's input to make it. For everything else, a good PR description or a message in the channel respects people's time more.

To sum up

An RFC isn't done when every section has text in it. It's done when your team can read it, understand it, and make a decision with it.

Start with the decision. Give just enough context. Split the plan into slices, ask the questions that matter, and make sure you understand every line. Your team will notice, and they'll read your next one too.