What makes a good design document, and when do you require one?

Summary

A good design doc is a short argument about trade-offs: context and scope, goals and non-goals, the design, alternatives considered, risks and rollout. Require one for non-trivial changes — new services or data models, cross-team impact, money or security, hard-to-reverse choices.

Longer Answer

Keep docs to a few pages so they're actually read. Name two to four reviewers who are affected or have expertise, ask them specific questions, and set a decision date. The 'Alternatives considered' section is the heart: it shows why other options lost and prevents re-litigating later. Record the outcome in the doc and, for lasting decisions, in an ADR. Small, reversible changes only need a good PR description.

Key Points

• Trade-offs over completeness
• Named reviewers, specific questions, decision date
• Lasting decisions also go into an ADR

Deep dive: Design Docs and RFCs That Get Read

What interviewers look for

Pragmatism about when docs are needed, focus on trade-offs and decisions, and a process that gets to a decision.

Red flags

• Docs for everything, or for nothing
• 30-page specifications nobody reads