A customer asks your support team a question. Your colleague opens the Confluence page they wrote eight months ago, skims it, and answers with 70% confidence. Later, it turns out the behaviour changed in January. Nobody updated the doc.
This happens everywhere, all the time. According to Atlassian's own research, teams waste 25% of their working week searching for answers that should already be documented. Google found that poor documentation is the second-biggest barrier to developer onboarding. And yet every team I've spoken to treats this as a discipline problem — if only people would just keep the docs up to date.
They won't. Not because they're lazy. Because the system is broken.
The spec describes intent. Code describes reality.
Documentation is almost always written before the build. A PM writes a spec, the engineers build against it, and then — during implementation — edge cases surface, requirements get refined, business logic turns out to have three exceptions nobody anticipated. The spec captures the pre-build conversation. The code captures what was actually decided.
By the time the feature ships, the spec is already slightly wrong. Nobody goes back to fix it because they're already on the next thing. Every sprint, the gap widens.
The DORA 2024 report found that documentation quality is directly linked to organisational performance — but also that most teams know this and still can't close the gap. The problem is not awareness. It is that nothing in your development process generates the documentation automatically. It is always a separate, parallel, manually maintained task.
Only 4% of companies consistently document their processes (BPTrends). The other 96% are not failing — they are being rational. Maintenance is invisible work with no owner and no deadline.
Nobody owns it after it ships
During planning, the PM owns the spec. During development, engineers own the build. After launch, the spec exists in a grey zone where everyone assumes someone else is responsible.
You cannot fix this with process. "Make engineers update the spec before closing the ticket" sounds sensible, breaks immediately, and is already on your team's list of good intentions that do not survive contact with a deadline. The link between code and documentation is entirely human — and human links break the moment attention goes elsewhere.
This is not a willpower problem. It is a structural problem.
The uncomfortable truth
Your codebase already contains a perfectly accurate, always-current description of how your product behaves. Every business rule is encoded there. Every edge case is handled — or explicitly not handled — in a specific, unambiguous way. The code is the authoritative record. It just is not readable by the people who most need it.
A PM cannot scan a TypeScript file to find out whether a validation rule changed. A customer success manager cannot query a database schema to understand what triggered a user-facing error message. So we write documentation — as a translation layer between code and the rest of the organisation. But we write it once and hope it stays current. It does not.
The question is not "how do we get people to maintain their docs better." The question is "why aren't the docs automatically derived from the only source that's always correct."
If you use Confluence for product behaviour documentation, that comparison is worth reading directly — it is not a tool problem so much as a structural one.
The answer is a spec that derives its content from the code rather than from someone's memory of it. When behaviour changes in the code, the spec changes too — not because someone remembered, but because the spec is downstream of the code. That is what a living product specification is.
The demo project shows what this looks like in practice — a real spec generated from a real codebase, updated on every release. No account required. If you want to connect your own repository, get started free.
