Living documentation, and the drift it fixes

Living documentation is documentation that stays accurate as the system it describes changes. The term predates AI — it comes from the docs-as-code and behavior-driven-development worlds — but the idea is simple: docs should be derived from, and kept in sync with, a source of truth rather than maintained by hand on a separate island.

The opposite is the wiki everyone has: a page that was correct at launch, drifted out of date over a few sprints, and is now actively misleading — so no one trusts it, so no one updates it.

Drift isn't a discipline problem; it's a structural one. Code and docs live in different places, change on different schedules, and are owned by different incentives. A pull request that ships a feature is rewarded; the doc update that should accompany it is invisible and optional.

AI-assisted coding makes this worse. When agents write a large share of new code, it ships faster than any human can document — and the gap between what the system does and what the docs say widens every week.

Keeping documentation current can't depend on remembering to do it. In practice it takes three things working together:

There's a newer reason this matters. Documentation is no longer read only by people — AI coding agents read it too, to learn your conventions and architecture before they write. Stale docs don't just mislead a new hire; they teach your agents the wrong patterns.

That raises the bar. Living documentation becomes the shared source of truth that keeps both your team and your agents working from the same, current understanding of the system.