Writing Better RFCs and Design Docs

RFCs (Request for Comments) and design docs are how engineering teams align on the “what” and “why” before writing code. Done well, they reduce rework and create a record of decisions. Done poorly, they sit unread or trigger endless debate. Here’s how to write better RFCs and design docs that get read, get feedback, and lead to decisions. Why Write Them at All? Alignment: Everyone works from the same understanding of the problem and the approach. Async review: People can respond in their own time, including across time zones. Memory: Later you have a record of why you chose X and what you rejected. Onboarding: New joiners (and future you) can understand the system without digging through code and chat. The goal is a shared decision, not a perfect document. Write for clarity and decision-making, not for length. Structure That Works 1. Context and problem. What’s the situation? What’s broken or missing? One to three short paragraphs. If the reader doesn’t understand the problem, the rest