Design Documents and RFCs
What you'll learn: How to create detailed written proposals that thoroughly explore planned technical changes before implementation begins.
What Are Design Documents and RFCs?
A Design Document (or RFC — Request for Comments) is a formal written proposal that describes a planned change to a system. Unlike a README that explains what already exists, or API documentation that describes current functionality, design docs explain what you plan to build and why before you build it.
Think of it like an architect's blueprint before construction begins. You wouldn't start building a bridge without detailed plans showing the design, materials, structural calculations, and alternative approaches considered. Design docs serve the same purpose for software.
Core Components
A strong design document typically includes:
- Problem statement: What issue are you solving?
- Goals and non-goals: What's in scope and what isn't?
- Proposed solution: Your technical approach with enough detail for others to understand and critique
- Alternatives considered: Other approaches you evaluated and why you rejected them
- Trade-offs and risks: Honest assessment of downsides and concerns
- Migration or rollout plan: How you'll safely implement the change
Why They Matter
Design docs create asynchronous alignment. Your stakeholders (as you learned to identify and manage) can review and comment on your plan before you invest weeks of development time. They surface blind spots, gather expertise from across teams, and create a permanent record of why decisions were made.
The "RFC" naming emphasizes that you're requesting comments — inviting constructive feedback from your team, just as you do in code review.
Key Takeaway: Design documents are detailed, written proposals that explore planned technical changes, alternatives considered, and trade-offs before implementation, enabling team alignment and better decision-making.