Michael Lynch has written design docs at Google, Microsoft and his own companies. This excerpt from his book Refactoring English is the most concrete treatment of the form I’ve read, mostly because every recommendation ships with actual example prose — a fictional caching layer called RecencyBank — instead of a heading checklist.

The organising idea is that a design doc is not a specification. It forces you through the decisions before you write the wrong implementation, and it’s the cheapest way to get teammates aligned.

What belongs in it comes down to one question:

  • What’s the penalty for being wrong? Irreversible choices go in; reversible ones don’t.
  • Building a web app in C++ and realizing 200k lines later that you wanted Rails is a design-level mistake. Whether a list shows 100 items or 25 with a “Load more” button is not — “you can fix it in a few hours.”
  • If the doc specifies every detail, you’ve written the implementation during the design phase, which defeats the point.
  • Investment scales with risk. “Sometimes, the right amount to invest in a design doc is zero.”

When it’s worth writing one:

  • Multiple people coordinating the work, or more than three months of full-time effort
  • The system runs in production for years, or involves cross-team collaboration
  • Goals are ambiguous, or there are catastrophic risks you can prevent at design time (security, legal)
  • One “yes” makes it likely worth it; two or more makes it almost certain

The sections he walks through, each demonstrated: title, metadata, objective, background, related documents, goals, non-goals, scenarios, diagrams, glossary, constraints, SLOs, monitoring, timeline, interfaces, dependencies, security, privacy, legal, logging, open and resolved issues, alternatives considered. He’s explicit that you pick the subset that applies.

A few bits that carry more weight than the list:

  • Goals state impact, not implementation. “Add Kubernetes to our infrastructure” is a bad goal; “minimize outages when deploying new app versions” is a good one.
  • Non-goals exist to kill assumptions readers arrived with — e.g. this cache will not become a general-purpose caching system.
  • SLOs beat vague requirements. “Performant on mobile” might mean 2ms or 200ms, and you don’t want to find out after code complete.
  • Milestones should produce artifacts stakeholders can react to. Ship the UI with dummy data first, so a requirements misunderstanding surfaces before the plumbing exists.
  • Diagrams must be editable. A photographed whiteboard looks brilliant once and is then frozen forever.
  • Open issues are a first-class appendix — problem, options, next step. Resolved ones move down, keeping the decision and the original discussion.
  • Alternatives considered should be short. Meticulously archiving every rejected idea is overkill; a few lines on the strong ones is enough.

The deeper claim is that the doc’s value isn’t its length. It’s the arguments it settles before anyone writes code, and the surface it gives reviewers to push back on. Review gets a companion piece precisely because driving feedback — rather than letting it turn into bickering — is its own skill.

He also admits he’s never seen a public design doc he considers high quality, so he published his own, written before any code and still being implemented against.