How to Write a Compelling Technical RFC

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:

1. Explains the problem clearly — even to someone unfamiliar with the area
2. Proposes a specific solution — with enough detail to evaluate it
3. 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.

Navigating Nuance: Addressing Language Barriers in Technical Communication

Writing a compelling technical RFC – especially when you’re not entirely fluent in English – can feel daunting. It’s easy to fall into patterns that don’t fully convey your ideas or, worse, create misunderstandings. Let’s be honest, the pressure of presenting complex technical details while simultaneously grappling with unfamiliar vocabulary and sentence structures is significant. A common issue we see is developers using overly simplistic phrasing – sometimes unintentionally – because they’re trying to minimize ambiguity, but this can actually make things more confusing for reviewers who expect a certain level of precision and formality.

One key area to focus on is clarity through active voice and precise verbs. Instead of saying “It has been observed that…” try “We’ve noticed that…”. This shifts the emphasis from passive observation to your team’s understanding and proposed solution. Similarly, replacing vague terms like “this” or “it” with specific references – for example, referring back to a particular issue number or component name – dramatically improves comprehension. During code reviews, you might receive a comment like: “Could you elaborate on the rationale behind this change?” A good response isn’t just “It works.” It’s, “We observed increased latency in scenario X, and this refactoring optimizes the data flow by utilizing [specific algorithm/method] as detailed in document Y. The goal is to reduce average response time by approximately 15%, as measured by our internal benchmarks.” See how that’s more specific and clearly articulates the why?

Another frequent challenge for non-native speakers is understanding the expectations around formality within technical documentation. RFCs aren’t casual Slack conversations; they require a level of professional tone. Phrases like “I think” or “maybe we could…” are generally avoided, replaced with more assertive statements like “This design addresses…” or “We propose implementing…”. When crafting your PR descriptions, avoid using overly tentative language. Instead of saying, “Perhaps this approach would be beneficial,” state clearly: “Implementing this optimization will improve performance by X%.” Finally, always double-check your grammar and spelling – tools like Grammarly can be invaluable, but don’t rely solely on them; a fresh pair of eyes (ideally someone familiar with the project) is crucial for catching subtle errors.