Writing RFCs & Design Docs

The RFC is the primary tool of Staff-level influence. A well-written RFC can align twenty engineers across five teams, prevent months of rework, and create a shared understanding that no number of meetings can achieve. A poorly written one wastes everyone's time, generates confusion, and makes you look unprepared.

Most Staff Engineers underestimate how much of their impact comes through written documents. You may spend only a few days writing an RFC, but the decisions it drives and the alignment it creates can shape the engineering organization for years.

This chapter covers how to write RFCs and design docs that actually work — that get read, generate productive feedback, and lead to decisions.

RFCs vs Design Docs

These terms are often used interchangeably, but they serve different purposes.

RFCs (Requests for Comments)

An RFC proposes a significant change and solicits feedback from the broader organization. It is a decision-making document. The goal is to reach agreement on an approach before implementation begins.

RFCs are appropriate when:

The change affects multiple teams.
There are multiple viable approaches with different trade-offs.
The decision is hard to reverse once implemented.
You need organizational buy-in to proceed.

Design Docs

A design doc describes how a specific system or feature will be built. It is an implementation planning document. The goal is to communicate the design clearly enough that any engineer on the team could implement it.

Design docs are appropriate when:

The implementation is complex enough that coding without a plan is risky.
Multiple engineers will work on different parts of the system.
You want a written record of design decisions for future maintainers.

A Staff Engineer at a payments company wrote an RFC proposing that all services migrate from REST to gRPC for internal communication. After the RFC was approved, each team wrote a design doc for their specific service migration. The RFC set the direction; the design docs handled the details.

RFC Structure

Every organization develops its own template, but effective RFCs share common elements.

RFC: [Title]
Author: [Name]
Status: Draft / In Review / Approved / Rejected / Superseded
Date: [Date]
Reviewers: [Names]

## Summary
One paragraph. What are you proposing and why?

## Motivation
What problem does this solve? Why now? Include data.

## Detailed Design
The technical proposal. Enough detail to evaluate trade-offs,
not so much that it reads like implementation code.

## Alternatives Considered
What other approaches did you evaluate? Why did you reject them?

## Migration Plan
How do we get from here to there? Phased rollout? Feature flags?

## Risks & Open Questions
What could go wrong? What have you not figured out yet?

## Timeline
Rough phases and milestones. Not a project plan.

The Summary

The summary is the most important paragraph in the document. Many readers will read only this. It must convey what you are proposing, why it matters, and the key trade-off in three to five sentences.

Bad summary: "This RFC proposes changes to our authentication system to improve security and developer experience."

Good summary: "This RFC proposes replacing our per-service authentication with a centralized auth gateway. Today, 14 services implement their own auth logic, leading to three security incidents in the last year from inconsistent token validation. The proposed gateway centralizes auth into a single service, reducing the security surface area and eliminating 2,000 lines of duplicated code. The trade-off is a new single point of failure, mitigated by the design described in Section 3."

Motivation with Data

The motivation section is where you earn the reader's attention. Lead with data, not opinions.

A Staff Engineer at a healthcare company wanted to propose a new testing framework. Instead of writing "our current testing approach is slow and flaky," they gathered data:

Current state (last 90 days):
- Average CI pipeline duration: 47 minutes (up from 22 minutes a year ago)
- Flaky test rate: 8.3% of test runs fail due to non-deterministic tests
- Engineer hours spent investigating flaky tests: ~120 hours/month
- Teams that have disabled integration tests entirely: 3 of 11

This data made the case self-evident. Nobody argued about whether there was a problem — the discussion immediately moved to solutions.

Alternatives Considered

This section is where trust is built or lost. If you present only one option, readers suspect you have not done your homework. If you present alternatives but dismiss them superficially, they will not trust your judgment.

For each alternative, explain:

What the approach is.
Its advantages over your proposal.
Why you ultimately rejected it, with specific reasoning.

Acknowledging the strengths of rejected alternatives shows intellectual honesty and prevents reviewers from wasting time advocating for approaches you have already evaluated.

Risks & Open Questions

Admitting what you do not know builds more credibility than pretending you have all the answers. Experienced reviewers can smell false confidence. They trust authors who clearly separate what they know from what they are uncertain about.

List specific open questions and propose how to resolve each one — a spike, a conversation with a specific person, a prototype.

Writing Persuasively for Technical Audiences

Technical readers are skeptical by default. They have read bad proposals before. Persuasion in this context is not about rhetoric — it is about evidence, clarity, and intellectual honesty.

Lead with the Problem, Not the Solution

Engineers are problem-solvers. If you start with the solution, they will immediately generate their own alternative solutions and spend the rest of the document comparing theirs to yours. If you start with the problem and build toward the solution, they follow your reasoning and arrive at the conclusion with you.

Be Concrete

Abstract statements generate abstract objections. Concrete examples generate specific, productive feedback.

Weak: "The current system does not scale well."

Strong: "At current growth (15% month-over-month), the order service will exceed its database connection pool limit by August. Here is the query that will fail first, based on current p99 latency trends."

Anticipate Objections

Before publishing, ask yourself: "What will the skeptics say?" Then address those objections directly in the document. This is not defensive writing — it shows that you have thought rigorously about the trade-offs.

If a likely objection is "this adds a new single point of failure," include a section on failure modes and mitigation before anyone raises it.

Use Concrete Scenarios

Walk through a specific scenario to illustrate how the proposed system works. "When a user initiates a payment, the request flows through the gateway, which validates the token, enriches the request with user metadata, and forwards it to the payment service" is easier to evaluate than an abstract description of the architecture.

Pre-Socialization

The biggest mistake Staff Engineers make with RFCs is treating the review period as the first time anyone hears about the proposal. By the time you publish, the key stakeholders should already know what you are proposing and have had a chance to raise concerns privately.

Why Pre-Socialize

You catch fatal flaws early. A fifteen-minute conversation with the database team lead might reveal a constraint that invalidates your entire approach — better to discover this before you spend a week writing the full RFC.
You build allies. When someone has influenced the proposal, they feel ownership over it. They become advocates rather than critics during the review period.
You reduce surprise. Technical leaders who feel blindsided by a proposal that affects their domain will oppose it on principle. Nobody likes learning about a major change to their system from an email.

How to Pre-Socialize

Start with a one-pager. Write a one-page summary of the problem and your proposed direction. Share it with three to five key stakeholders.
Have one-on-one conversations. Walk through the one-pager with each stakeholder individually. Ask: "What am I missing? What concerns you about this approach?"
Incorporate feedback. Update the one-pager based on what you hear. Send the updated version back: "Based on your feedback, I changed the approach to X. Does this address your concern?"
Write the full RFC. By this point, you know the objections, you have addressed the biggest ones, and your key stakeholders feel heard.

A Staff Engineer at a ride-sharing company pre-socialized an RFC proposing a new event-driven architecture over three weeks. By the time the full RFC was published, every team lead had already given input. The review period was two days. The previous RFC (not pre-socialized) took six weeks of contentious debate.

Handling Feedback & Dissent

Productive Feedback

Most feedback falls into a few categories:

Clarification requests: "I do not understand how X handles Y." This means your writing is unclear. Fix the document and thank the reviewer.
Missing considerations: "What about Z?" If it is a real gap, acknowledge it and update the RFC. If you considered it, explain why you excluded it.
Alternative approaches: "Have you considered doing X instead?" Evaluate honestly. If it is better, adopt it. If not, explain why in the Alternatives section.

Unproductive Feedback

Some feedback is not useful but still requires handling:

Bikeshedding. Extensive debate on minor details (naming, formatting, style) while ignoring the core design. Acknowledge the input, make a quick decision, and redirect: "Good point on the naming. I will use ServiceGateway. Can we discuss the failover strategy?"
"I would have done it differently" without specifics. Ask for specifics: "Can you describe the approach you have in mind and the trade-offs? I want to make sure I am not missing something."
Scope expansion. "While we are at it, we should also fix Y and Z." Resist. "Y and Z are real problems, but I want to keep this RFC focused. I will file follow-up RFCs for those."

When Someone Strongly Disagrees

If a senior engineer or a team lead fundamentally opposes your proposal, do not try to resolve it in document comments. Schedule a face-to-face (or video) meeting. Understand their concern fully. Often, a 30-minute conversation resolves what would otherwise become weeks of comment threads.

If you cannot reach agreement, escalate to a decision-maker you both respect. Frame it as: "We have two viable approaches with different trade-offs. Here is a clear description of both. We need someone to make the call."

When to Write vs When to Talk

Not every decision needs an RFC. Writing is expensive — a good RFC takes days to write and days for reviewers to process.

Write an RFC when:
- The decision affects multiple teams
- The decision is hard to reverse
- There are meaningful trade-offs to evaluate
- You need a written record for future context

Just talk when:
- The decision affects only your team
- The decision is easily reversible
- There is a clear best option and you just need agreement
- The discussion requires real-time back-and-forth to resolve ambiguity

A Staff Engineer who writes an RFC for every decision will exhaust their reviewers. A Staff Engineer who never writes RFCs will make decisions without organizational buy-in. The judgment of when to write versus when to talk is itself a Staff-level skill.

Making RFCs Actionable

An RFC that gets approved but never implemented is worse than no RFC — it creates the illusion of progress. Every RFC should end with clear next steps:

Next steps:
1. [Name] creates the shared library repository by [date]
2. [Team A] migrates their service in Sprint 14
3. [Team B] migrates their service in Sprint 15
4. Author reviews each migration PR for consistency
5. Retrospective after all migrations complete

Assign owners and dates. If the RFC does not have clear ownership of next steps, it will stall.

Common Pitfalls

Writing the RFC after you have already decided. If the document reads like a justification rather than an exploration, reviewers will sense it and disengage. The RFC process must genuinely allow for alternative outcomes.
Skipping pre-socialization. Publishing a major proposal without warning key stakeholders guarantees opposition. Invest the time in one-on-one conversations before the formal review.
Over-engineering the document. A 40-page RFC with appendices and footnotes will not get read. Most decisions can be captured in 5-10 pages. Write the minimum needed to evaluate the trade-offs.
Under-specifying the migration path. The design is often the easy part. How you get from here to there — the migration plan, the rollback strategy, the phased rollout — is where most proposals fail. Give migration at least as much attention as design.
Ignoring feedback you disagree with. Every piece of feedback deserves a response. If you disagree, explain why. Ignoring comments signals arrogance and discourages future reviewers from engaging.
Letting RFCs languish in review. Set a review deadline (one to two weeks) and a decision date. If consensus is not reached, escalate to a decision-maker. Indefinite review periods kill momentum.
Not writing at all. Some Staff Engineers avoid writing because they are more comfortable talking through decisions in meetings. But meetings leave no record, include only the people in the room, and are forgotten within a week. Write the important decisions down.

Key Takeaways

The RFC is the primary tool of Staff-level influence — a well-written one aligns teams and prevents months of rework; a poorly written one wastes everyone's time.
RFCs are decision-making documents (proposing change and soliciting feedback); design docs are implementation planning documents (describing how to build something).
Every RFC needs a strong summary, data-driven motivation, a thorough Alternatives Considered section, and an honest Risks & Open Questions section.
Pre-socialize before publishing: share a one-pager with key stakeholders, have one-on-one conversations, and incorporate feedback before the formal review.
Technical persuasion comes from evidence, clarity, and intellectual honesty — not rhetoric. Lead with the problem, be concrete, and anticipate objections.
Handle feedback gracefully: clarify where writing is unclear, evaluate alternatives honestly, resist scope expansion, and resolve strong disagreements face-to-face rather than in comment threads.
Set review deadlines and escalate when consensus stalls; indefinite review periods kill momentum.
End every RFC with clear next steps, assigned owners, and dates — an approved RFC without ownership is an illusion of progress.
Know when to write and when to talk; not every decision needs an RFC, but every important cross-team decision does.