## Definition **Living documentation** is a set of executable specifications that stay current because the system itself keeps them honest. In Gojko Adzic's framing in [[Specification by Example - Gojko Adzic]], it becomes the "canonical description of what the application does" — and it can outlive the production code it was written against. ## Why ordinary documentation dies Prose docs decay the moment they are written, because nothing forces them to track the code. Every change is a chance to forget the doc. The standard result is a wiki that everyone distrusts and nobody updates. Living documentation escapes this by being *executed*: if it diverges from the system, a test fails, and the divergence is caught instead of accumulating. ## The one-way dependency The mechanism is a deliberate direction of dependency. Automation depends on the spec; the spec does not depend on the automation. ``` spec (examples) <-- automation/glue code <-- system under test ``` You automate the *validation* of an example without rewriting the example. The Gherkin stays in business language; a step-definition layer binds it to code. This is what lets the documentation read like documentation while still running like a test. Invert the arrow — let the spec be generated from the code — and you get a description that is always accurate and always useless, because it merely restates the implementation. ## Outliving the code Adzic's striking claim is that the spec can outlast the code. Reimplement the service in another language and the executable specifications remain valid — they describe *behaviour*, not implementation. This is why they form the durable asset: code is a current answer; the spec is the question. ## Relationship to SDD In [[Spec-Driven Development]] the spec is the prompt that drives an agent to write code. Living documentation is the same artifact viewed from the other side: after generation, the executable spec keeps verifying that the generated code still does what was asked. The [[Executable Acceptance Criterion]] is the atom; living documentation is the corpus those atoms form. ## Practical discipline - Keep examples in business vocabulary, not in API calls. - Run them in CI so drift breaks the build, not someone's trust. - Prune dead examples — a living document with corpses in it is just a different kind of stale. ## Related - [[Specification by Example]] - [[Executable Acceptance Criterion]] - [[Spec-Driven Development]] - [[Gherkin Scenario]]