← All posts

# Why I stopped writing RFCs (and what I write instead)

Published January 22, 2026

After ten years of formal design docs, I changed the format. Here is what I do now and the kind of decisions it tends to produce.

- #process
- #engineering-orgs

I used to be the person at every company who insisted on RFCs. Title, motivation, design, alternatives, security, rollout, alternatives-considered. The whole template. I believed — and I still believe — that writing forces clarity, and that a good RFC is the artifact of a real decision.

I have stopped writing them.

## What changed

Three things, in order of how slowly I noticed them:

The artifact stopped being the decision. People would ship the thing the RFC described, then later produce work that diverged from it because reality is messier than the doc. The doc became a historical fiction. New hires would find it, treat it as authoritative, and act surprised when the code didn’t match.

The review process started selecting for the wrong thing. Long-form docs reward people who write fast and confidently in the format. They do not reward people who think carefully. I watched two genuinely better designs lose to RFCs that were merely earlier and more polished, three jobs in a row.

The decision was almost always made before the doc was written. Not always; not by everyone. But the median case was: someone has the design in their head, writes it up, posts it, and the “review” is a polite re-statement of objections that the author dispatches in comments. The doc was performance.

## What I write instead

A two-section memo. First section: the decision and why. Three to five paragraphs, written after a rough prototype exists. Second section: the open questions I want pushback on, listed individually. Not “thoughts welcome” — specific questions, each with my best current guess.

The memo is shorter than an RFC. It is also more honest. It does not pretend the decision is up for grabs when it isn’t. It asks for help with the parts that genuinely are.

## Has it worked?

For me, yes. The decisions I’ve shipped from memos have aged better than the ones I shipped from RFCs, because the memo format makes me write the prototype first and the doc second. The prototype is where the real thinking happens.

This is not advice. I am one engineer in one career. RFCs work for plenty of people and plenty of orgs. But if you’ve been feeling that the docs you’re producing are doing less work than the time you’re spending on them — try this for a quarter and see.

Free MIT template · Day 1 of 365

You're looking at a demo. Download the built static files (no Astro needed — drop on any host) or grab the full source to customize.

↓ Download static (HTML/CSS/JS) ↓ Source (Astro) All 365 → Build with me →