How to Write a Compelling Technical RFC
A practical guide to writing technical RFCs (Request for Comments) in English — structure, vocabulary, and phrases that get your proposals approved.
An RFC (Request for Comments) is a document proposing a technical change, new system, or significant decision — and inviting the team to review and discuss it before implementation begins. Writing a compelling RFC is both a technical and a writing skill. A well-written RFC gets approved faster, generates more useful feedback, and builds your reputation as an engineer who thinks clearly.
What Makes an RFC Compelling
A good RFC does three things:
- Explains the problem clearly — even to someone unfamiliar with the area
- Proposes a specific solution — with enough detail to evaluate it
- Acknowledges trade-offs honestly — showing you’ve considered alternatives
RFCs that skip step 3 often fail to gain consensus because reviewers suspect the author hasn’t thought it through.
Standard RFC Structure
Title and Metadata
RFC-042: Migrate Authentication Service to JWT-Based Tokens
Status: Draft
Author: [Your name]
Created: 2026-06-13
Reviewers: [Names]
Summary (2–4 sentences)
Write this last, but put it first. It should tell the reader what you’re proposing and why, in plain English:
“This RFC proposes migrating our current session-based authentication to stateless JWT tokens. The primary motivation is to support horizontal scaling of the API tier without shared session storage. The expected outcome is a 40% reduction in database load from session queries and simpler infrastructure for multi-region deployment.”
Problem Statement
“Currently, user sessions are stored in Redis and queried on every authenticated request. This creates a stateful dependency that prevents the API servers from scaling independently. As we prepare for multi-region deployment, this architecture becomes a significant constraint.”
Use the present tense to describe the current state. Be specific — include metrics where you have them.
Proposed Solution
“We propose replacing session tokens with signed JWT (JSON Web Tokens). The token will be issued at login, contain the user ID and role, and be signed with an RS256 private key. Tokens will expire after 15 minutes; a refresh token with a 7-day expiry will allow seamless re-authentication without requiring the user to log in again.”
Break complex proposals into numbered steps or subsections. Use diagrams where they clarify (reference them as “see Figure 1”).
Alternatives Considered
This section demonstrates intellectual honesty:
“We considered three alternatives before arriving at this proposal:”
“Option A — Keep the current session store but switch to a distributed cache. This would reduce latency but does not solve the fundamental statefulness problem for multi-region deployment.”
“Option B — Use opaque tokens with a central token validation service. This avoids embedding user data in the token, but introduces a new service dependency on every authenticated request.”
“Option C (proposed) — Stateless JWTs. Eliminates the session store dependency, enables horizontal scaling, and is industry-standard. The trade-off is that tokens cannot be immediately revoked without an additional blocklist mechanism.”
Trade-offs and Risks
“Token revocation complexity: Unlike session tokens, JWTs cannot be invalidated before expiry. We will mitigate this by using short expiry times (15 minutes) and maintaining a blocklist for high-risk events such as password changes and account suspension.”
“Key rotation: If the signing key is compromised, all tokens become invalid simultaneously. We will implement automated key rotation with a 90-day cycle.”
Implementation Plan
“Phase 1 (2 weeks): Implement JWT issuance and validation in the auth service. Deploy behind a feature flag.”
“Phase 2 (1 week): Migrate internal services to validate JWTs. Remove session store dependency.”
“Phase 3 (ongoing): Monitor error rates and latency. Remove the feature flag.”
Language Patterns for RFCs
Proposing:
“We propose… / This RFC proposes… / The recommended approach is…”
Explaining rationale:
“The primary motivation is… / The reason for this approach is… / This is preferred because…”
Acknowledging trade-offs:
“The main trade-off is… / One limitation of this approach is… / This does not address X, which will be handled separately.”
Requesting feedback:
“Feedback is particularly welcome on… / We are uncertain about… / Input from the security team would be valuable here.”
Common RFC Mistakes
- Too vague: “We should improve the authentication system.” — this is not a proposal, it is a wish.
- No alternatives: Skipping this section makes reviewers feel manipulated.
- No success criteria: How will you know if the change worked? Add measurable outcomes.
- Too long: An RFC is not a technical specification. Aim for 800–1,500 words. Link to specs in appendices.
A well-written RFC is one of the highest-leverage documents an engineer can produce. It aligns teams before work begins, surfaces problems early, and creates a permanent record of why decisions were made. Invest the time to write it well.