Design docs at Google (2020)

Greendoc template and design doc variants

• Some describe Google’s go/greendoc template as extremely minimal (few headings, ~2 pages) and not very useful outside Google; others say it was helpful, though teams often evolved their own formats.
• Newer or junior engineers can find the “official” template overwhelming and instead copy structure from existing team docs.

Perceived benefits of design docs

• Help authors clarify their own thinking, expose flaws, and size the work before coding.
• Force consideration of cross‑cutting concerns (monitoring, reliability, security, privacy, observability), often via “use standard system X” but still ensuring they’re addressed.
• Enable async review across large, geographically distributed teams and serve as historical context for future engineers.
• Useful for onboarding, stakeholder alignment, and mentoring juniors (who learn to justify choices and get feedback).

Common failure modes and criticisms

• Many Google docs are seen as low‑value: promo pieces, jargon “word salads,” overlong new‑grad docs, or fact‑light “best practice” assertions.
• Docs can become de facto substitutes for real, maintained documentation, even though they’re outdated as soon as implementation diverges.
• Design‑by‑committee and endless comment cycles can delay decisions; authors resist simpler solutions that undermine a “big” design they invested in.
• For trivial or well‑trodden work, docs feel like busywork; some report weeks of delay waiting for sign‑off that arrives after the feature ships.

Promotion, incentives, and “fake work”

• Many describe design docs at Google (and elsewhere) as primary promotion artifacts; engineers write them “for the committee.”
• This drives behaviors like inflating complexity, inventing weak alternatives, avoiding co‑authors, and tracking docs by individual rather than team.
• There’s broader debate over what “impact” metrics should be and how easily they get cargo‑culted.

Comparisons with other companies

• Amazon’s doc culture is praised for seriousness and clear decision‑making via single‑threaded owners, though some say Amazon design docs are often stale and the process can devolve into committee alignment as orgs grow.
• Other large firms reportedly encourage similar “alternatives considered” rituals.

Process, upfront design, and alternatives

• Some argue fully upfront design is unrealistic; in practice, good docs are often written or substantially revised after implementation (“fake rational process”).
• Others advocate lightweight, early docs, one‑pagers for obvious changes, and using tickets + whiteboards for small teams.
• Several links (Chromium, Kubernetes KEPs, Oxide RFDs) are cited as real‑world examples, often more rollout/justification than pure upfront design.