How to Write an RFC Document in English

An RFC exists to get a proposal reviewed and improved before it’s built, which means its phrasing has a specific job: present a clear recommendation while genuinely inviting disagreement, rather than reading as a decision already made that’s just being announced. The language that does this well is confident about the problem and honest about the uncertainty in the solution.

Key Vocabulary

Framing the problem before the solution — establishing clearly what problem is being solved and why it matters, before presenting any proposed approach, so readers can evaluate the solution against the actual need. “I framed the problem before the solution: our current retry logic causes duplicate charges under network partitions, and that’s the specific problem this RFC addresses.”

Presenting alternatives considered — listing other approaches that were evaluated and explaining why they were set aside, which shows the proposal wasn’t chosen in a vacuum. “I presented the alternatives considered: we also evaluated a queue-based approach, but ruled it out due to the operational overhead of running a new piece of infrastructure.”

Stating tradeoffs honestly — acknowledging genuine downsides or risks of the proposed approach, rather than presenting it as having no drawbacks. “I stated the tradeoffs honestly: this approach adds latency to the write path, which we’re accepting in exchange for stronger consistency guarantees.”

Marking open questions explicitly — calling out decisions that are genuinely still undecided and inviting input, distinct from decisions the author considers already settled. “I marked the open questions explicitly: we haven’t decided on the retry backoff parameters yet, and feedback here would directly shape the implementation.”

Common Phrases

• “The problem: [specific, concrete description of what’s broken or missing and its impact].”
• “Proposal: [specific approach], because [specific reasoning tied back to the problem].”
• “Alternatives considered: [approach A] — rejected because [reason]. [Approach B] — rejected because [reason].”
• “Tradeoffs: this approach [specific downside], in exchange for [specific benefit].”
• “Open questions: [specific undecided point] — feedback welcome, particularly from [specific team/expertise].”

Example Sentences

A clear problem statement: “Currently, a network partition during payment processing can cause a webhook to be retried in a way that charges the customer twice. This has happened three times in the last quarter, each requiring a manual refund and support ticket.”

Presenting alternatives with honest reasoning: “We considered introducing a message queue to guarantee exactly-once processing, but rejected it for now given the operational cost of running and monitoring new infrastructure for a problem we believe idempotency keys solve more simply.”

Stating a tradeoff without minimizing it: “This adds a small amount of latency to every payment request, since we’re now checking an idempotency key against a lookup table before proceeding. We think this tradeoff is worth it given the cost of duplicate charges, but it’s worth discussing whether that latency is acceptable for our highest-throughput customers.”

Inviting disagreement genuinely, not performatively: “I’m not fully confident in the proposed TTL for the idempotency key cache — if anyone has seen this pattern fail at scale, I’d like to hear about it before we finalize this.”

Professional Tips

• Frame the problem clearly and concretely before introducing any solution — a reader who doesn’t understand the problem can’t evaluate the proposal on its merits.
• Include alternatives considered, even briefly, since it shows the proposal was chosen deliberately rather than being the only option that occurred to the author.
• State tradeoffs honestly, including genuine downsides — an RFC that presents its own proposal as flawless reads as less trustworthy, not more persuasive.
• Mark open questions explicitly and distinguish them from settled decisions, so reviewers know exactly where their input can actually change the outcome.
• Avoid presenting the RFC as a decision already made — phrasing like “we will do X” reads very differently from “we’re proposing X, and here’s why,” even when the underlying plan is the same.

Practice Exercise

1. Write a two-sentence problem statement for a hypothetical technical issue, without mentioning any solution yet.
2. Write an “alternatives considered” entry that rejects an approach with a specific, honest reason.
3. Write an “open questions” section entry that genuinely invites disagreement on a specific undecided point.

Navigating Nuance: Refining Your English for Technical Proposals

Writing an RFC – a Request For Comments – is already challenging. It requires precision, clarity, and the ability to articulate a complex idea in a way others can understand. But for developers who are learning professional English, the subtleties of technical phrasing can feel particularly daunting. Beyond simply using correct grammar and vocabulary, it’s about adopting the style of communication expected within a software development environment – a style that prioritizes conciseness, objectivity, and a focus on collaboration. A common mistake non-native speakers make is attempting to translate directly from their native language’s technical terminology, leading to awkward phrasing or concepts misunderstood by reviewers. Don’t fall into this trap; aim for the clearest possible expression in English, even if it means sacrificing a perfectly accurate literal translation.

One key area of focus should be around expressing uncertainty and inviting feedback. Phrases like “This is currently an assumption…” or “We are exploring alternative approaches that… ” immediately signal to reviewers that you’re open to discussion and aren’t presenting a definitive solution. Similarly, when describing potential drawbacks, avoid overly assertive statements like “This will never be a problem.” Instead, frame it as a consideration: “A potential challenge with this approach is [specific issue], which we are currently investigating.” Another frequent pitfall is using overly complex sentence structures. Strive for sentences that convey your idea efficiently – breaking down longer clauses into shorter, more digestible ones improves comprehension significantly. Remember, the goal of an RFC isn’t to impress with your vocabulary; it’s to facilitate productive discussion.

Let’s consider a practical scenario. Imagine you’re submitting a PR describing a proposed change to the authentication system. A reviewer might respond with: “This looks interesting, but I’m not seeing how this addresses the performance concerns we discussed last week. Could you elaborate on the expected impact?” A less effective response from you would be something like, “We implemented a new algorithm to improve speed.” This is too vague and doesn’t invite discussion. A stronger approach would be: “To address the previous performance concerns, we’ve implemented an optimized algorithm for [specific operation]. However, we acknowledge that further testing is needed to fully quantify the impact. We welcome feedback on whether this change aligns with our performance goals and if there are alternative strategies we should consider.” Notice the use of phrases like “we acknowledge,” “further testing is needed,” and “welcome feedback,” actively promoting a collaborative environment.

Finally, pay close attention to how you frame questions. Rather than asking, “Is this good?”, which can sound presumptuous, ask: “What are your thoughts on the trade-offs between [benefit] and [potential drawback]? Are there other factors we should be considering?” Phrasing requests for feedback in this way demonstrates respect for others’ expertise and encourages a more thoughtful response. Mastering these subtle nuances will not only improve the clarity of your RFCs but also demonstrate that you’re actively engaged in a collaborative, professional environment – crucial skills for any developer seeking to thrive in a team setting.