Design Doc vs RFC — Structure & Language
When to write each, RFC openings, review states, RFC → Design Doc sequence, and decision documentation
Design doc and RFC essentials
- Design Doc: how to build something already decided — aligns team on approach
- RFC: what to do is still open — seeks broad feedback before deciding
- RFC opening: what is proposed + who is being asked + what feedback is sought
- Review states: LGTM = approve; approved with comments = approve + suggestions; blocking concern = must resolve first
- Every Design Doc decision needs: alternatives considered + why rejected + trade-offs accepted
Question 0 of 5
What is the fundamental difference between a Design Doc and an RFC (Request for Comments)?
Design Doc = aligning on how to build (approach is clear); RFC = seeking consensus before deciding. When to write each:
- Design Doc: "We have decided to build X. This document describes the approach so the team can review the implementation plan before we start." — the what is decided, the how is being aligned
- RFC: "We are considering changing our authentication approach. We have not decided yet. We are seeking feedback from engineers across teams before proceeding." — even the what is open
- ✅ Design Doc: "Design for the rate limiter service" — you're building a rate limiter, this is how
- ✅ RFC: "RFC: Should we migrate from REST to GraphQL?" — open question, seeking input
Which opening sentence is correct for an RFC?
RFC opening = what is proposed + who is being asked + what kind of feedback is sought. RFC opening formula:
- Proposal: "replacing our monolithic deployment pipeline with per-service CI/CD pipelines" — clear and specific
- Status signal: "we are seeking feedback before proceeding" — unambiguous that this is not decided
- Audience: "platform, backend, and mobile teams" — tells readers this affects them and invites them in
- Focus: "specifically on the migration path and tooling choices" — guides feedback so reviewers know what to address
What do the review states "LGTM", "approved with comments", and "blocking concern" mean in the context of RFC review?
LGTM = approve; approved with comments = approve + suggestions; blocking concern = must resolve before proceeding. RFC review vocabulary:
- LGTM (Looks Good To Me): reviewer has no objections; proceed
- Approved with comments: reviewer approves the overall approach but has suggestions the author should consider — not blocking, but flagged for discussion
- Blocking concern: reviewer believes this specific issue must be resolved before the RFC can be accepted — the RFC cannot proceed to implementation until this is addressed
- Needs revision: the overall approach has problems that require a rework of the proposal, not just a clarification
- Label every comment: "blocking concern:", "suggestion:", "question:" — don't leave reviewers guessing whether to act on it
- Respond to all comments in the doc before closing the RFC — document why you accepted or rejected each piece of feedback
A team writes a Design Doc for a new search service. A reviewer asks: "Have you considered using Elasticsearch instead of building a custom solution?" This question arrives after the Design Doc is published. What does this suggest?
Major alternative questions after the Design Doc signal the RFC phase was skipped or too narrow. RFC → Design Doc sequence:
- RFC phase: "Should we build a custom search solution or adopt an existing one? We are evaluating custom, Elasticsearch, and Typesense." — gather broad input
- Design Doc phase: "We have evaluated the options (see RFC-0042) and selected Elasticsearch. This document describes how we will implement it." — align on the chosen approach
- The RFC was either not done, too narrowly circulated, or not read by key stakeholders
- A late "have you considered X?" question can derail an implementation that has already started — costly and frustrating
- The fix: make RFC circulation broad, require acknowledgment from affected teams, and explicitly list alternatives considered before writing the Design Doc
A Design Doc section reads: "We will implement authentication using JSON Web Tokens." What critical information is missing?
Every major decision in a Design Doc needs: alternatives considered + why rejected + trade-offs accepted. Decision documentation formula:
- ❌ "We will use JWT" — gives the reader the decision but not the reasoning
- ✅ "We evaluated three authentication approaches: session-based (rejected: doesn't support our stateless API design), OAuth2 (rejected: adds third-party dependency for internal APIs), and JWT. We chose JWT for its stateless nature — enabling horizontal scaling without shared session state. Trade-off accepted: token revocation requires a blacklist — we will implement a Redis-backed blacklist for logout and account compromise scenarios."
- A reader 18 months later who wants to change the approach needs to know what was already evaluated — otherwise the same analysis is repeated
- Documenting rejected alternatives prevents "have you thought about X?" questions during review
- Acknowledged trade-offs show the team was thoughtful, not naive