Specs as forcing functions
The common complaint about specs is that nobody reads them after week one. Mostly true — and mostly irrelevant, because a spec's primary value is not as a reference document. It's as a forcing function: a structure that makes decisions happen while they're still cheap to change.
What writing forces
Every section of a good spec template is a decision the team would otherwise defer to the most expensive possible moment:
- Non-goals force the scope fight before the sprint, not during it.
- Success metrics force agreement on what "done and working" means before anyone is emotionally invested in shipping.
- User journeys force the edge cases into view while they cost a paragraph, not a redesign.
- Open questions force honesty about what is still unknown — a section whose emptiness is itself a signal worth distrusting.
Top-down, then inward
The sequencing that works for me: outline the whole structure first — modules, journeys, boundaries — and only then develop each section. Depth-first writing produces beautifully specified corners of systems whose overall shape was never decided. The outline is where the architecture conversation actually happens; the sections merely record its consequences.
The litmus test
If writing the spec changed no decisions, you didn't write a spec — you wrote minutes for a meeting that hadn't happened.
This is also why generated or templated specs feel hollow when used naively: the artifact appears without the decisions occurring. The document was never the point. The same principle drives good training design — structure exists to force engagement, not to hold content (see progressive complexity).