Docs that stay alive: writing specs your team actually reads
Most engineering specs are dead the day they ship. Here is how we write specs at Clustra so they stay useful three months later — and why "living docs" is a wiring problem, not a writing problem.
A spec is written for two audiences: the team that ships it, and the engineer six months from now trying to understand why. Almost every spec optimizes for the first audience and fails the second. The doc goes stale two weeks after ship, and by month three the person who wrote it cannot remember what the section on "future considerations" was about. We spent a lot of time trying to fix this by writing better. Turns out the fix is upstream: the wiring around the doc, not the doc itself.
The shape of a Clustra spec
Every spec starts from the same template. Five sections, in this order:
- Problem — one paragraph, no jargon. What breaks if we do nothing? Who is hurt?
- Non-goals — a bulleted list of what this proposal is explicitly not solving. This section stops more scope creep than anything else in the doc.
- Proposal — the shape of the solution, at the altitude where trade-offs live.
- Alternatives considered — every other shape we discussed, each with the one-line reason we rejected it.
- Open questions — the list of things we do not yet know. This section is what keeps the doc alive.
Why the wiring matters more than the writing
A spec becomes dead the moment it stops being connected to the work. If you write a spec, ship the feature, and never link back — the spec is a fossil. In Clustra we wire specs to work in three specific ways.
- 01
Every issue in Plan links back to its spec
You cannot merge a PR against a Plan issue that has no linked spec. The link is the accountability.
- 02
The spec embeds live data from Plan
When the spec says "we will ship three phases," the phase status lives in the doc as an embedded Plan view. The doc updates as the work does.
- 03
The open questions section stays open
When a question resolves, it moves to a "decisions log" section — with a date and a link to the conversation that resolved it. Future you knows why.
How we review specs
Written review before verbal review. The author posts the doc, asks two named reviewers for a written pass, and only after those comments are addressed do we schedule a 30-minute discussion. Written-first review is slower for a day and dramatically faster for a week — because it forces the reviewer to load the whole context, not just the last paragraph the author is talking about.
The template
Every Clustra workspace ships with this spec template preinstalled in Notes. If you want to try the shape without switching tools, the five headings work in any editor. The magic is not the template. The magic is treating the doc as connected tissue — a living record wired to the work it describes.