What is a design document, and why write one?
A written proposal describing what you intend to build and why, circulated before the work starts. Its value is not the document — it is that writing forces you to confront decisions you would otherwise discover halfway through implementation.
What it typically contains:
Context and problem statement, including why this matters now.
Goals, and — critically — non-goals, which prevent scope arguments later and are the section most often omitted.
The proposed design, at a level someone could critique without reading code.
Alternatives considered and rejected, with reasons. This is the highest-value section: it demonstrates the space was explored, and it is what a reader six months from now actually needs.
Trade-offs and risks, stated honestly.
Impact on existing systems — migration, compatibility, operations, security, privacy, cost.
A rollout and rollback plan.
Open questions, which invite exactly the input you want.
Why it is worth the time:
Writing surfaces incoherence. A design that sounds fine spoken frequently falls apart when written precisely — which is the point, and is far cheaper than discovering it in code.
Review scales. Ten people can read a document asynchronously; a meeting cannot accommodate their attention, and reviewing a large change after it is built produces only superficial comments, because nobody will ask for a rewrite at that stage.
It records the why. Code shows what was done; a design document explains what was considered and rejected, which is precisely what is lost otherwise.
It surfaces objections while they are cheap. The security or operations concern that arrives on day two is an adjustment; on the day before launch it is a rebuild.
When to skip it. Small, reversible or well-precedented changes do not need one. Use judgement based on cost of being wrong, not on size.
How to make it work: keep it short — two to five pages beats twenty; circulate it early enough for objections to matter; set a review deadline; record the decision and reasoning in the document itself; and keep it as a historical record rather than updating it into documentation.