Writing Code is Only 30% of the Job: The Art of the Persuasive RFC
If you can't communicate your architectural decisions asynchronously, your impact is capped. Full stop.
I've watched genuinely brilliant engineers plateau at senior level not because they couldn't design systems, but because nobody outside their immediate team ever understood what they were proposing or why. Their ideas lived and died in their own heads, or got mangled in a 45-minute meeting where three people talked past each other and nothing got decided.
The RFC, a Request for Comments, is the fix. Not because it's a magic format. Because writing forces clarity in a way that talking never does.
Why Engineers Under-Invest in Written Communication
We get hired to build things. The feedback loop is fast and satisfying. You write code, the tests pass, the PR merges. It feels like progress because it is progress, measurable and visible.
Writing a document feels slower. Less concrete. And if you've ever spent two hours on a proposal that got ignored, you've probably decided it wasn't worth the effort.
But here's what that trade-off actually costs you: scope. The engineers who get pulled into architecture conversations, who get credited for the direction of a system, who get promoted into staff roles, they're not just better at coding. They're better at making their thinking legible to other people. That skill compounds. Every decision you can land asynchronously is a decision that doesn't require you to be in the room.
Your career ceiling is largely a function of how far your ideas can travel without you.
What an RFC Actually Is (And What It Isn't)
An RFC is just a written proposal that invites structured feedback before a decision is made. That's it.
The format matters less than the intent. You don't need a 15-section Notion template with a custom status workflow. You need a document that gives people enough context to have a real opinion, and a clear ask for what kind of feedback you're looking for.
The goal isn't consensus. It's alignment. Those are different things. Consensus means everyone agrees. Alignment means everyone understands the decision, the tradeoffs, and why it was made, even if some people would have chosen differently.
A good RFC gets you to alignment without a two-hour meeting.
The Anatomy of a Persuasive RFC
Context: Assume Nothing
This section is the one people skip, and it's the most important one.
Your readers don't have the three weeks of background you have. The PM who approved the project doesn't remember every detail from the planning doc. The designer joining halfway through doesn't know what the legacy system does. Write the context as if someone smart but completely new to the problem is reading it, because someone like that almost certainly is.
This doesn't mean padding. It means being specific about the situation: what the system currently does, what constraints exist, what's changed recently that makes this worth solving now.
Pro tip: If you find yourself saying "as everyone knows" or "obviously," delete that phrase and explain the thing. Nothing shuts down participation faster than making someone feel dumb for not knowing the background.
Problem Statement: Make It Measurable
Vague problem statements are where RFCs go to die. "Our current architecture doesn't scale" tells nobody anything. Scale to what? Under what conditions? How do you know?
Be specific. Attach numbers where you can. "At our current growth rate we'll hit the rate limit on this third-party API within six weeks, which will start causing request failures for roughly 40% of users during peak hours" is a problem statement. It has a timeline, a mechanism, and a real impact.
The more specific the problem, the easier it is for reviewers to engage with your solution. And the easier it is to know, later, whether you actually solved it.
Proposed Solution: Write to Be Critiqued
Explain the how, with enough detail that someone can poke holes in it. Not implementation line-by-line, but the key design decisions, the dependencies, the parts you're least certain about.
Don't oversell it. The engineers reading this will trust you more if you write like a person who has thought carefully about a problem than like a person who has found the One True Answer. There is rarely a One True Answer.
Alternatives Considered: This Is Where Trust Lives
This section is the difference between a document that gets buy-in and one that gets ignored or relitigated.
When you show that you considered other approaches and explain why you didn't go with them, you signal that your recommendation isn't just the first thing you thought of. You show the shape of the decision space. You preempt the "but have you thought about X" question that otherwise eats 20 minutes of review time.
Even if the alternatives were bad, write them down. Especially if they were bad. Explaining why something doesn't work is often more convincing than explaining why something does.
Open Questions: Intellectual Honesty Is a Superpower
List the things you're not sure about. The places where you made an assumption that might be wrong. The parts that depend on information you don't have yet.
Engineers often avoid this because it feels like admitting weakness. It's the opposite. It shows you know where the edges of your knowledge are, which is exactly what you want from someone making architectural decisions. It also gives reviewers a clear place to add value.
Pro tip: Frame open questions as questions, not hedge statements. "I'm not sure if this will work" helps nobody. "Does our current auth service support the token refresh pattern described in section 3?" is something someone can actually answer.
Success Metrics: How Will You Know It Worked?
Define what success looks like before you build the thing. This is good engineering practice and it's also very good politics. It means the conversation about whether the project succeeded is grounded in something objective.
Pick metrics that are directly influenced by your change. Keep it to two or three. If you can't name what moves as a result of this work, that's worth figuring out before you start.
Writing for Multiple Audiences
Here's something people get wrong: they write one RFC for everyone and it lands for nobody.
PMs care about outcomes. They want to know what user problem this solves and what the expected impact is. Lead with that. Make it easy to find.
Engineers care about tradeoffs. They want to understand what you're giving up, what the operational complexity looks like, where the failure modes are. Put the depth there.
Designers care about user impact. How does this change what a user experiences? Are there new states, new flows, new edge cases that need to be designed for? Call that out explicitly.
You don't need three separate documents. You need a structure that lets each audience skim to what matters to them and go deep when they want to. Good headers do a lot of this work.
Getting Useful Feedback Instead of Silence or Bikeshedding
Write the document. Share it. Wait for feedback. Get nothing for five days, then a comment thread about the name of a variable. This is the default outcome if you don't actively manage the review process.
A few things that actually help:
- Set a decision deadline in the document. "I'm planning to start implementation on [date] unless there are significant objections." This creates a forcing function. Without one, review drifts forever.
- Tag specific people for specific sections. "Hey [designer], the flow in section 4 is where I'd most value your input" gets you a real response. A generic "PTAL" gets you a thumbs up.
- Distinguish between blocking concerns and preferences. When you ask for feedback, explicitly ask reviewers to flag whether a comment is a blocker or a nice-to-have. This prevents endless threads about things that don't actually change the decision.
- Post a summary update when the decision is made. Close the loop. One paragraph explaining what was decided and what changed from the original proposal. This builds trust in the process over time.
Common RFC Mistakes
Most RFC failures trace back to one of these:
- Vague problem statement. If someone can read your problem section and say "well, it depends," you haven't been specific enough.
- Skipping alternatives. This is the fastest way to get relitigated in review. Do the work upfront.
- No decision deadline. Documents without deadlines drift. Someone will always have one more concern.
- Writing for yourself. If you already know all the context, it's easy to forget that your readers don't. Reread it as if you joined the team last week.
- Burying the ask. What do you actually need from reviewers? Spell it out at the top.
When Not to Write an RFC
Not everything needs one. If the decision is easily reversible, scope it small and just ship it. If you're the only person affected, write a comment in the code. If the decision needs to be made in the next hour, a doc is not the right tool.
RFCs are for decisions that are hard to reverse, affect multiple people or systems, or require input from people outside your immediate team. Use that as your filter. The overhead is worth it when the stakes are high enough.
Writing an RFC for every small decision is just bureaucracy with better branding.
A Pokemon Aside (Stay With Me)
If this post had a spirit Pokemon it would be Alakazam. Hear me out. Alakazam has an IQ of 5,000 and can hold every calculation in its head simultaneously, but it only reaches its final form through trade, through connection with another trainer, through the act of sharing. Brilliant in isolation, exponentially more powerful when it communicates. That's the RFC in a nutshell.
The Bottom Line
The engineers I've watched grow the fastest weren't the best coders on their teams. They were the best communicators. Not in a polished, corporate way. In a precise, clear, "I've thought about this and here's what I think we should do and here's why" way.
Writing a good RFC is that skill made concrete. It's the practice of taking something complicated that lives in your head and making it navigable for someone else. Do it consistently and you become the person whose ideas actually get built, not because you argued loudest in a meeting, but because your reasoning was there in writing, patient and clear, waiting for anyone who wanted to engage with it.
Write the document. Set the deadline. Close the loop.
The meeting you didn't have to schedule is the meeting everyone is grateful you skipped.