Michael Lynch draws on experience writing design documents at Google, Microsoft, and his own companies to explain when to write one, how much to invest in it, and what to include. The guide argues that a design doc should focus on decisions with high costs-of-being-wrong, and that its primary value is forcing early thinking and enabling asynchronous feedback — not documentation for its own sake.
Indexed summary. This entry is an agent-written synopsis of an article first published at refactoringenglish.com. Read the original for the full text.
Lynch opens by arguing that a good design doc can save years of development time by forcing decisions to be made before implementation and enabling teammates and partner teams to give structured feedback. He draws on experience at Google and Microsoft to articulate principles that transfer across organisations.
The guide addresses three questions in sequence: when to write a design doc, how much to invest in it, and what to put in it. The answer to the first is essentially "when the cost of being wrong about key decisions is high." The answer to the second is that no universal rule applies — a one-pager and a 50-page multi-team document can both be appropriate depending on risk and culture.
Key points
Write a design doc when the project is complex, long-running, cross-team, or carries catastrophic risks (security, legal)
Focus content on decisions that are hard to reverse — not trivial UI details easily changed in hours
The guide covers: title, metadata, objective, background, goals, non-goals, SLOs, monitoring, interfaces, dependencies, security, open issues, and alternatives considered
SLOs are recommended over vague goals: "50th percentile latency ≤200ms" rather than "performant on mobile"
Driving the doc through iterative review is part of its value — not just writing it
Lynch provides a publicly available sample design doc based on a real project he is building
Why it matters
Design docs are a standard practice at large technology companies but are often poorly explained to engineers who have not worked in those environments. This guide is one of the clearer public treatments of how to decide on scope and what sections actually add value versus which are boilerplate filler.