Docs & Code Guide

Living documentation vs docs-as-code: a property and a process, and why neither implies the other

Docs-as-code is a process: documentation stored in version control as plain text, changed through pull requests, built and published by CI. Living documentation is a property: the content is generated from the system it describes, so it cannot silently diverge from reality. The terms get used interchangeably and they should not be, because a team can run a flawless docs-as-code pipeline around hand-written pages that lie, and a generated schema view can be fully living without ever touching git.

Try it free
7 min readFor teams deciding where to invest their documentation effort

See it as a diagram

Everything below, as a diagram you can edit. Describe yours and see it in seconds.

141/2000• 3 credits left
Try:

No account needed · Editable canvas, not a picture

A process and a property

Docs-as-code describes how documentation is handled: Markdown or AsciiDoc in the same version control as the code, changes reviewed like code changes, output built and deployed by the same CI. The term spread through the Write the Docs community and Anne Gentle's book Docs Like Code. Its promise is process quality: history, review, and docs that can ship in the same PR as the change they describe.

Living documentation describes what documentation is: generated or derived from the authoritative source, so it stays true by construction. The canonical treatment is Cyrille Martraire's book Living Documentation, which names four qualities to aim for: reliable, low effort, collaborative, insightful. A test suite whose names describe behavior, an API reference emitted from code annotations, and a schema view rendered from the live database are all living. None of them requires git to be so.

The confusion costs real money: teams migrate a wiki into git expecting accuracy to improve, and get the same stale prose with better version history.

The four quadrants

Crossing the two axes gives four quadrants, and every documentation artifact on your team sits in exactly one of them.

Both (living, as-code): an OpenAPI reference generated from code annotations and built in CI, or dbt docs emitted by the pipeline that runs the models. Process-only (as-code, not living): hand-written architecture decision records in the repo, reviewed in PRs; the process is exemplary and the content still goes stale by hand. Property-only (living, not as-code): a schema visualizer reading the live database, or a diagram an agent regenerates from the repository into a canvas tool; nothing lives in git, yet the content tracks reality. Neither: hand-edited pages in Confluence or Notion, which is where most architecture documentation actually lives.

                 docs-as-code (process)      not docs-as-code
living         | OpenAPI ref generated     | schema view rendered from
(generated     | from annotations,         | the live database; diagram
from the       | built in CI; dbt docs     | an agent redraws from the
system)        |                           | repo into a canvas tool
---------------+---------------------------+--------------------------
not living     | hand-written ADRs and     | hand-edited wiki pages in
(maintained    | Markdown guides in git,   | Confluence or Notion
by hand)       | reviewed in PRs           |

Where diagrams land in each quadrant

A hand-written Mermaid diagram in the repo is docs-as-code but not living: it versions and reviews beautifully and drifts exactly as fast as a wiki drawing. It is still the right choice for small flows that live next to the prose describing them; Mermaid renders natively in GitHub fenced blocks and only starts fighting you past roughly 20 nodes, a boundary docs-as-code diagram limits maps in detail.

A Mermaid file emitted by a script in CI is both living and as-code, the strongest position when a generator for your view exists. A Datadef diagram sits in the property-only quadrant: an agent connected to its MCP server regenerates the diagram from what it reads in the repository, invoked after a merge or in CI rather than by watching the repo, and the canvas itself lives outside git. Its embed URL then drops into any docs-as-code page as a plain Markdown image, and an edit shows up in the rendered page within minutes. The two approaches compose rather than compete.

Which to invest in first

Invest by change rate. Content that changes with every release, API surfaces, schemas, architecture topology, pays back the living property fastest, because that is where manual updates fail first. Content whose value is judgment rather than state, ADRs, postmortems, design rationale, pays back the process: those documents are write-once, and what they need is review and permanence, not regeneration.

The failure mode to avoid is buying the process as a proxy for the property. Moving stale prose into git gives it version history and a build pipeline; it does not make it true. If accuracy is the problem, generation and a single source of truth are the levers, and the anchor guide on living documentation covers making that shift.

The one-sentence version

Docs-as-code makes documentation reviewable. Living documentation makes it true. High-churn content needs the property; judgment content needs the process; the best surfaces use each where it pays.

FAQ

What is the difference between living documentation and docs-as-code?

Docs-as-code is a process: documentation in version control as plain text, changed via pull requests, built and published by CI. Living documentation is a property: content generated from the system it describes, so it cannot silently drift. They are independent: hand-written Markdown in git is docs-as-code without being living, and a schema view rendered from a live database is living without being docs-as-code.

What does docs-as-code mean exactly?

Treating documentation with the same toolchain as code: plain-text sources (Markdown, AsciiDoc) in the same repository, changes proposed and reviewed as pull requests, output built and deployed by CI. The term spread through the Write the Docs community and Anne Gentle's book Docs Like Code. It guarantees history and review; it does not by itself guarantee the content is current.

What is living documentation?

Documentation generated or derived from the authoritative source rather than maintained by hand, so it stays accurate by construction. The term comes from Cyrille Martraire's book Living Documentation, which sets four goals: reliable, low effort, collaborative, insightful. Examples: an API reference emitted from code annotations, dbt docs built by the pipeline, an architecture diagram an agent regenerates from the repository.

Does putting docs in git make them living documentation?

No. Git gives documentation history, review, and a build pipeline, which is docs-as-code. Living requires the content to be generated from the system, so that divergence is impossible rather than merely visible. Hand-written pages drift at the same speed in git as in a wiki; the difference is only that git can tell you when the page was last touched.

Are Mermaid diagrams living documentation?

Only if something generates them. A hand-written Mermaid block is docs-as-code: versioned and reviewable, but it drifts like any manual drawing. A Mermaid file produced by a script in CI from the actual system is both docs-as-code and living. Hand-written Mermaid remains a good fit for small flows near their prose; it gets unwieldy past roughly 20 nodes.