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.