Design Docs: When to Write, When to Skip (Decision Framework)
A mid-size team I advised last year had a standing rule: every ticket above 3 story points needed a design doc. Eight engineers, roughly four docs per week, each doc eating a half-day to write and another half-day in review cycles. That's 32 engineering hours per week — four full working days a week, spent on documents that most people scanned once and never reopened. The CTO thought they were a high-discipline shop. The data said they were documentation-heavy and velocity-poor.
The opposite extreme is worse. A 2019 report from Stack Overflow's Developer Survey listed "poor documentation of internal systems" as the #2 productivity blocker after technical debt itself. Skipping design docs entirely means every sixth-month refactor is an archaeology dig.
This is the framework I use to decide which changes deserve a doc, which deserve a 3-sentence RFC comment, and which deserve nothing at all.
