Writing an RFC (Request for Comments) Document
Practice the structure and language of RFC documents for engineering teams.
RFC document structure
- Title: Verb + subject + scope — specific enough to distinguish from related RFCs
- Problem statement: quantified pain, root cause, stands alone without the solution
- Motivation: "The current approach has the following limitations:" — bulleted, independent
- Proposal: specific technology, version, config, edge cases handled
- Drawbacks: "One concern with this approach is..." — mechanism + acceptability condition
- Unresolved questions: framed as decisions, with current thinking and resolution path
Question 0 of 5
Which excerpt correctly writes an RFC title and problem statement?
An RFC title must name the specific action, the subject, and the scope. The problem statement must quantify the pain before proposing a solution.
- Title pattern — Verb + subject + for/in + scope: "Replace X with Y for Z". Specific enough to distinguish from other caching RFCs the team might produce.
- Problem statement first — the problem section should stand alone and be compelling without the solution. If the reader agrees the problem is real and costly, they are primed to evaluate the proposal fairly.
- Quantified pain — "18ms p50, 94ms p99" — turns a subjective complaint ("caching is slow") into an objective, measurable baseline that the solution can be evaluated against.
- Root cause framing — "network round-trip on every authenticated request" — explains the mechanism, which later guides the solution design.
Which passage correctly writes the "Motivation" section of an RFC?
The "Motivation" section is a bulleted list of specific, independent limitations of the current approach — not a generic complaint.
- "The current approach has the following limitations:" — the standard opening phrase. It is neutral and sets up a structured list, not an emotional argument.
- Each limitation is independent — a reader who disagrees with one can still accept the others. Bundling all problems into one sentence prevents this.
- Quantified where possible — "200–800ms queuing latency on 3–5% of requests" — this is evidence, not assertion.
- Non-obvious costs included — "operational complexity" and "on-call burden" are legitimate costs that are often omitted from purely technical motivation sections, but matter to engineering managers and on-call engineers.
Which passage correctly writes the "Proposal" section of an RFC?
The "Proposal" section describes exactly what will be built — the component, the library, the configuration, and how edge cases are handled.
- Specific technology named — "
lru-cachev10" — not just "an LRU cache library". The version number matters for dependency audits. - Configuration specified — "10,000 entries, 5-minute TTL" — reviewers can evaluate whether these values are appropriate without asking.
- Consistency maintained — "consistent with the current Redis TTL" — explicitly connecting the proposal to the existing system prevents accidental behaviour changes.
- Edge case addressed — "cache invalidation on logout via pub/sub" — demonstrates that the author has thought through the hard part. An RFC that proposes a cache without addressing invalidation is incomplete.
Which sentence correctly writes a "Drawbacks" or "Concerns" section in an RFC?
The "Drawbacks" section must name a specific technical concern, explain the mechanism, quantify the impact, and state the conditions under which it is or is not acceptable.
- "One concern with this approach is..." — the standard opening phrase. Neutral framing that acknowledges the issue without abandoning the proposal.
- Mechanism explained — "cache inconsistency between instances during invalidation propagation window" — the reviewer understands the failure mode, not just that it exists.
- Quantified window — "50–200ms" — places the concern in practical terms.
- Acceptability condition — "acceptable for session reads, not acceptable for permission or role data" — this constraint is critical. It bounds the proposal: the author is proposing this approach only for session data, and is signalling that the approach should not be extended to permission checking without re-evaluation.
Which passage correctly writes an "Unresolved questions" section in an RFC?
The "Unresolved questions" section explicitly surfaces decisions that the RFC author cannot make alone — it invites targeted input from reviewers.
- Each question framed as a decision — "What should the maximum cache size be?" — not just "caching is complex".
- Current thinking stated — "10,000 entries is a reasonable starting point" — the author is not abdicating, just acknowledging uncertainty. This saves reviewers from re-deriving a starting point.
- Why it is unresolved — "we do not have data on session payload size distribution" — explains what information is needed to close the question.
- How to resolve it — "we should profile session sizes before finalising" — turns the question into an action item with a clear resolution path.