Living documentation: the concept, and the tools that deliver it

The test that separates living documentation from well-maintained documentation: if the system changes and no human edits the doc, does the doc still tell the truth, or at least admit that it might not? A doc that passes is living. A doc that fails is merely current, and current is a temporary condition; the gap that opens afterwards is documentation drift.

Note what the definition does not require: it does not require the doc to be in the repo, to be generated, or to involve AI. Those are mechanisms, and there are exactly three.

Generation. The doc is rebuilt from source on every change: OpenAPI reference from the spec, dbt docs from the models, terraform-docs from the modules. A generated doc cannot drift, only fail to regenerate, and a build step catches that. The limit is scope: generation covers what the machine can see, never the why.

Verification. The doc is hand-written, but something checks it against the source and flags it when it becomes suspect: coupled code references, CI rules that pair code paths with doc paths, link checkers. Verification does not keep docs true, it keeps their staleness visible, which turns silent rot into a review comment.

Live reference. Consumers point at the source artifact instead of a copy. An embedded diagram that renders from a canvas, rather than a pasted screenshot of one, is current in every doc the moment the canvas changes. Nothing was regenerated and nothing was verified; the copy step that drifts was simply removed.

No product covers all three mechanisms across all doc types, so the honest way to map the landscape is by slice. Ordered by how fast each slice usually rots. (For a comparison organized by approach rather than by product, see best tools to keep docs and code in sync.)

Architecture diagrams: Datadef. Diagrams rot fastest because they are usually exported images, and nobody re-exports on change. Datadef attacks that with the live-reference mechanism: the diagram is a canvas, and every embed in a README, Notion, or Confluence follows it, so one edit updates every copy. For the edit itself, the canvas is exposed as an MCP server, so a coding agent that just changed the system can regenerate the diagram from the repository in the same session. Scope is the honest limit: this covers the diagram slice, not prose, and without an agent a human still makes the edit at the source. The scratch canvas is free; embedding and MCP access are part of the subscription plans.

Code-coupled prose: Swimm. Swimm is the only tool on this list that verifies hand-written prose: docs reference specific code, CI flags a doc when the referenced code changes, and trivial changes such as renames are patched automatically. The strength is real verification; the limit is that coverage exists only for docs written in Swimm and coupled to snippets, so it earns its keep on codebases where the hard-won prose lives close to specific code. Pricing is a per-seat subscription with a free tier.

API reference: ReadMe, or plain OpenAPI generators. Spec-driven reference regenerates on every build, and ReadMe adds a hosted portal with an interactive explorer that syncs from the spec in CI. The caveat worth knowing: the docs are exactly as true as the spec. If the spec is hand-written and drifts from the implementation, the portal faithfully republishes the drift, so generate the spec from code where you can. ReadMe prices as a per-project subscription with a free tier; the plain generators are open source.

Product docs sites: Mintlify plus CI. MDX in the repo, deployed on merge, link checks in the pipeline, and docs that change in the same PR as the feature. This is docs-as-code with a strong publishing layer, and that is also its limit: nothing verifies that the prose matches the product, so it delivers visibility of change rather than truth. Pricing is a hosted subscription with a free tier.

Generated reference: dbt docs, terraform-docs, TypeDoc, Sphinx. The oldest and most reliable slice: pure generation, free and open source, rebuilt on every run. Data platforms lean on this hardest since schemas and models change daily; the data documentation guide covers that stack end to end. The limit is the same as all generation: reference only, no rationale.

Living documentation is adopted one doc at a time, not as a platform decision. The sequence that works: run the stale documentation audit to find the doc that lies most (in most teams it is the architecture diagram, or the deployment doc; a CI/CD pipeline diagram generated from a prompt is a fast replacement for that one). Give that doc a living mechanism, delete the copies it replaces, and let the team notice that one page can now be trusted without checking. Then take the next doc. The trust is the product; the tools are just how you afford it.