Design Doc

ELI5 - The Vibe Check

A design doc is the longer, more detailed cousin of an RFC, written after the team has basically agreed something should be built and now someone needs to actually think through how. It covers the architecture, the data flow, the tradeoffs between the approaches you considered, and the parts you're still unsure about, so the eventual reviewer of your PR isn't discovering your reasoning for the first time buried in a code comment.

Real Talk

A design doc is a written technical proposal describing the architecture, data model, interfaces, and tradeoffs of a planned system or feature in enough detail for reviewers to evaluate the approach before implementation, distinct from an RFC in that it typically assumes the should-we-do-this question is settled and focuses on how. The practice was popularized industry wide by Google's internal design doc culture and is now standard at most engineering organizations building anything beyond a small, self-contained change.

When You'll Hear This

"Skip the design doc for a one-line config change, but not for a new service." / "The design doc caught a scaling problem in review that would've been way more expensive to catch in production."