Design Docs That Earn Their Keep: When to Write One and What to Leave Out

Drawing on stints at Google, Microsoft, and his own startups, Michael Lynch argues that a design doc’s real value is forcing hard decisions before code gets written and giving teammates a concrete artifact to critique. The heuristic for whether to bother: score the project against risk factors like multi-person coordination, multi-year production lifespan, cross-team dependencies, ambiguous requirements, or preventable catastrophic risks such as security flaws. One yes makes a doc probably worth it; two or more makes it almost certain. There’s no fixed length — a one-pager and a 50-page multi-team signoff can both be correct, and sometimes the right investment is zero.

The key discipline is deciding what to include. The test is ‘what’s the penalty for being wrong?’ Costly, near-permanent choices (picking C++ over Rails for a web app you can’t feasibly rewrite) belong in the doc; cheap, reversible ones (a ‘Load more’ button versus showing all items) don’t and shouldn’t burn review cycles. Over-specifying every detail just recreates the implementation during the design phase, defeating the point.

Lynch also lays out the standard anatomy — a short, evocative title, metadata (author, creation date, canonical URL, signoff record), a one-sentence objective, background that explains motivation and prior attempts, links to related docs, and user- or business-framed goals rather than implementation-framed ones. A recurring theme is self-containment: assume some readers hit the doc cold, so everything they need to understand the project should sit on the first page. Notably, he claims he’s never seen a high-quality public design doc, so he wrote a full example from scratch for a real app he’s building.