Living documentation is documentation that stays in sync with the system it describes, instead of freezing the day it was written. The enemy is documentation drift: a doc is accurate on publish, the product moves, and within weeks it is quietly, confidently wrong — and the reader cannot tell fresh from stale. The usual fixes — a review checklist, a docs sprint, more discipline — lose to shipping every time. Draftlize takes a different route: docs are derived from a card graph, each carries a snapshot of the cards it was built from, and when an upstream decision changes, the doc flags itself stale.
Every doc is accurate the day it ships. The question is what happens on day ninety — whether it can tell you it went out of date, or just keeps reading as truth.
| Draftlize | Wiki / Confluence / markdown | |
|---|---|---|
| Where the doc comes from | Derived from source cards | Typed by hand, then detached |
| A source decision changes | The doc auto-flags stale | The doc silently goes wrong |
| Can you trust it at a glance? | Stale is marked, not guessed | You re-verify against the code |
| Can an AI agent rely on it? | Reads current cards via MCP | Reads whatever text is there |
| Who keeps it current | The substrate tracks drift | A docs sprint that never comes |
A doc is perfect on the day it is written and a chore to update forever after. Maintenance competes with shipping and loses, so the doc freezes while the system keeps moving — and the gap widens every release.
A page describing how billing works has no connection to the decision that set the billing rules. Change the rule and nothing tells the page it is now fiction. The dependency exists in reality but not in the tooling.
The worst part of drift is invisibility. A stale doc looks exactly like a current one, so the reader trusts it — and a doc that is confidently wrong is more expensive than no doc at all.
A design doc, a technical doc, or a spec is generated from the underlying cards — the decisions, requirements, and rationale — rather than typed as freestanding prose. The doc has a real source, not just an author.
When a doc is built, it records which cards it came from and when. That snapshot is what lets the system compare the doc against the current state of those cards — the link between doc and truth is stored, not remembered.
A background detector watches the source cards. Change one an ADR or spec depended on, and every doc derived from it flags stale — so the doc tells you it needs a look instead of waiting to be caught wrong.
The problem was never writing the docs. It is that a doc cannot tell when it stopped being true.Derive the doc from the decisions. When they move, the doc says so.
Living documentation is documentation that stays in sync with the system it describes, rather than freezing at the moment it was written. The term comes from the BDD world, where docs are generated from executable specifications. The broader idea is that documentation should be derived from a live source, so it updates or flags itself when the source changes.
Documentation drift is the gap that opens between a document and the reality it describes as the system evolves and the doc does not. It is dangerous because a drifted doc looks identical to a current one, so readers keep trusting it — a confidently wrong doc costs more than no doc at all.
The durable fix is to stop maintaining docs by hand and derive them from a single source, then flag them when that source changes. Draftlize generates docs from a card graph and records a snapshot of the source cards, so a background detector can flag a doc stale the moment an upstream decision moves.
Docs-as-code keeps documentation in version control next to the code so it ships through the same pipeline — a real improvement, but the doc is still prose someone has to remember to update. Living documentation on a card graph adds the missing link: the doc knows which decisions it depends on, so it can flag itself stale instead of relying on a human to notice.
Keep your decisions and specs as cards, derive your docs from them, and let each doc flag stale when a source decision moves.
Start free with $5