Design Docs & RFCs

A design doc exists to get disagreement to happen early, when it is cheap. If nobody could possibly object to your document, it probably is not saying anything.

Lead with the problem, not the solution. Readers cannot evaluate an approach without knowing what it is for. Open with the problem, why it matters now, and what happens if you do nothing.

State the constraints explicitly. Deadlines, team size, systems that cannot change, compliance requirements. Most disagreement in design reviews is really disagreement about constraints, surfaced late — writing them down converts an argument about taste into a check on facts.

Alternatives considered is the section that carries the document. It proves the choice was made rather than defaulted into, and it pre-empts the reviewer who arrives asking "why not X?". Give each alternative a fair description and a specific reason for rejection. An obviously strawmanned alternative undermines the whole document.

Name what you are trading away. Every design has a cost. A doc that lists only benefits reads as advocacy, and experienced reviewers discount it accordingly.

Non-goals prevent scope creep better than any other section. "This does not address multi-region failover" stops that discussion from consuming the review.

Make it reviewable. Specific questions you want answered, a decision deadline, and named owners. "Thoughts?" produces silence; "Does anyone object to the migration order in §4 by Thursday?" produces answers.

Record the decision and why. Six months on, the reasoning is the valuable part — the conclusion alone leaves the next person unable to tell whether the constraints still hold.