How to Write Technical RFCs: Advanced Language Guide

A Request for Comments (RFC) is one of the most powerful documents in an engineering organisation. It captures a proposed technical decision, invites feedback from stakeholders, and creates a durable record of why a choice was made. Writing a compelling RFC in English requires more than technical knowledge — it requires the ability to frame problems clearly, anticipate objections, and guide readers towards a well-reasoned conclusion.

Key Vocabulary

Motivation The motivation section of an RFC explains why the proposal exists — what problem it is solving and why solving it matters now. A strong motivation section earns the reader’s attention and sets the stakes for the decision. Example: “The motivation for this RFC is the increasing latency in our data ingestion pipeline, which has exceeded our SLA threshold on three occasions in the past month.”

Trade-off A trade-off is a situation where gaining one benefit requires accepting a corresponding cost or limitation. RFCs that acknowledge trade-offs honestly are more credible than those that present a proposal as purely beneficial. Example: “The main trade-off of this approach is increased operational complexity in exchange for lower latency.”

Considered alternative A considered alternative is a solution that was evaluated and rejected in favour of the proposed approach. Documenting considered alternatives shows intellectual rigour and helps future readers understand why other approaches were not chosen. Example: “One considered alternative was to use a message queue instead of direct HTTP calls. We rejected this because it would add operational overhead without meaningfully improving reliability for our use case.”

Drawback A drawback is a disadvantage or limitation of the proposed solution. Acknowledging drawbacks builds trust with readers and demonstrates that the author has thought critically about their proposal. Example: “A significant drawback of this approach is that it introduces a new service that the platform team will need to maintain.”

Unresolved question An unresolved question is an issue that the RFC author acknowledges they do not have a clear answer to, inviting the community to contribute thinking. Being explicit about what you do not know is a sign of intellectual honesty in RFC writing. Example: “One unresolved question is whether the caching layer will need to be region-specific, or whether a single global cache will suffice.”

Structure of an Effective RFC

Summary: One paragraph describing the proposal at the highest level. Should be readable by anyone in the organisation.

Motivation: What problem are we solving, and why does it matter? Include data where possible.

Detailed design: The proposed solution, described in enough detail that an engineer could implement it. Include diagrams where they aid understanding.

Trade-offs and drawbacks: Honest assessment of the costs of the proposed approach.

Considered alternatives: What else was evaluated? Why was it rejected?

Unresolved questions: What do we still need to figure out?

Implementation plan: How will this be rolled out? Who is responsible? What is the timeline?

Useful Phrases for RFC Writing

• “This RFC proposes a new approach to X, motivated by the need to Y.”
• “The current implementation has the following limitations: …”
• “We evaluated three alternative approaches before settling on this design.”
• “The main advantage of this approach is X; the corresponding trade-off is Y.”
• “We considered using Z but rejected it because …”
• “One open question that requires further investigation is …”
• “This proposal has been discussed with the affected teams and has their provisional support.”
• “The implementation will proceed in two phases: …”
• “Feedback is invited on all sections, but particularly on the proposed API contract in Section 3.”
• “This RFC supersedes RFC-0042, which proposed a similar but less scalable approach.”

Writing the Motivation Section

The motivation section is where many RFCs fail. Engineers tend to describe the problem technically before establishing why it matters. Start with the user or business impact, then describe the technical reality.

Weak: “The current caching layer uses Redis with a single primary node.”

Strong: “Our checkout service is experiencing latency spikes during peak traffic periods, causing 12% of users to abandon their basket before completing a purchase. Profiling indicates that the bottleneck is our single-node Redis cache, which becomes saturated at peak load.”

Use data to establish credibility. Specific numbers — error rates, latency measurements, cost figures — make the motivation concrete and hard to dismiss.

Handling Objections in RFC Language

A good RFC anticipates the most obvious objections and addresses them proactively in the “Drawbacks” or “Considered Alternatives” sections. This is more persuasive than waiting to be challenged.

Use concessive language to acknowledge objections fairly before rebutting them: “While it is true that this approach introduces additional complexity, the operational overhead is justified by the significant reliability improvement it provides.”

Avoid defensive or dismissive language. “This concern is not relevant” will alienate readers. Instead: “This is a valid concern. We have mitigated it by…”

The Role of Precision in RFC Language

Precise language is essential in technical documents. Vague phrases invite misinterpretation and lengthy comment threads. Compare:

Vague: “The system should respond quickly to user requests.” Precise: “The system must respond to 95% of user requests within 200ms, as measured over a 5-minute rolling window.”

Use “must,” “should,” and “may” consistently according to RFC 2119 conventions: “must” for absolute requirements, “should” for strong recommendations, and “may” for optional behaviours.

Practice Suggestion

Write a one-page RFC (approximately 400 words) for a fictional technical change — for example, migrating a service from REST to gRPC, adopting a new database, or introducing a new deployment strategy. Include a summary, motivation, the main design, one trade-off, one considered alternative, and one unresolved question. Focus on the language: use the phrases from this post, write in the active voice, and be precise with your requirements language.

Navigating Nuance: Precision for Non-Native Speakers

Writing a robust RFC – a Request For Comment – isn’t just about outlining a problem; it’s about clearly articulating why the problem exists, what potential solutions you envision, and how those solutions align with broader engineering goals. This requires a level of precision in English that can often feel daunting, particularly for developers whose first language isn’t English. It’s incredibly common to fall into patterns – perhaps overly informal phrasing or reliance on direct translations – that actually obscure your intent rather than clarify it. Let’s address some specific areas where non-native speakers frequently struggle and provide strategies for more effective communication within a technical context.

One key area is the use of conditional language. Rather than saying “We need to do X,” which can sound demanding, phrasing it as “It would be beneficial to explore X” or “Considering Y, we should investigate whether X could address this” introduces a degree of diplomacy and invites collaboration. Similarly, when describing potential drawbacks, avoid blunt statements like “This will break everything.” Instead, use phrases like “Potential impacts include…” or “We need to carefully assess the compatibility with…” followed by specific concerns – for example, “…and ensure it doesn’t introduce regressions in component Z.” The goal is to frame discussions constructively, demonstrating you’ve thought through potential consequences.

Another common pitfall lies in verb choice and level of formality. While a casual tone might be acceptable in internal Slack channels, an RFC demands a more elevated register. Phrases like “Let’s look at this” are perfectly fine for quick brainstorming but lack the weight needed to justify a significant architectural change. Opt instead for phrases like “We propose evaluating…” or “A thorough analysis suggests…” These demonstrate careful consideration and professional commitment. Furthermore, be mindful of overusing contractions – “it’s,” “we’re,” etc. – in formal writing can sound less polished. Strive for complete sentences where appropriate to reinforce clarity.

Finally, remember the importance of explicitly stating assumptions. Technical discussions are rife with unspoken understandings, but an RFC must lay out any underlying assumptions clearly. For instance, instead of simply stating “The API will be versioned,” add: “We assume a backwards-compatible versioning scheme will be employed, allowing for seamless integration with existing systems.” This proactive approach reduces the risk of misinterpretations and fosters greater alignment within the team. A recent Slack message from a teammate highlighted this perfectly: “Just wanted to flag that assuming all clients support HTTP/2 might be optimistic – let’s add a caveat about potential fallback mechanisms.”