Learning Objectives
By the end of this lesson you will be able to:
- Define Living Documentation and explain what makes it "alive"
- Explain why traditional documentation goes stale and Gherkin scenarios resist it
- Identify where Living Documentation fits alongside (not instead of) other docs
The Problem With Regular Documentation
You've seen this before: a wiki page titled "How Checkout Works," written eighteen months ago, describing a flow that was rewritten three sprints ago. Nobody deleted the page. Nobody updated it either. It sits there, confidently wrong, misleading the next person who searches for it.
Documentation goes stale because nothing forces it to stay in sync with the system it describes. Writing it and maintaining it are two separate acts of willpower, and the second one always loses.
What Makes Documentation "Living"
Living Documentation solves this by tying the documentation directly to executable verification. When Gherkin scenarios are automated (a later stage this course doesn't cover, but is worth knowing about), each scenario is literally run against the real system. If the scenario's description no longer matches reality, the automation fails — loudly, immediately, in the build pipeline. Nobody can silently let the description drift, because a red build forces someone to reconcile the two.
Even without automation, a well-written Gherkin scenario stays more accurate longer than prose, simply because its rigid structure makes drift more visible — a Then that no longer matches the app's behavior stands out much faster than a paragraph that vaguely still "sounds right."
Living Documentation Is Not a Replacement
This isn't a case for deleting your wiki. Living Documentation excels at describing specific, testable behaviors — not architecture diagrams, not onboarding guides, not "why we chose Postgres." Keep the narrative docs for narrative purposes. Use Gherkin scenarios for the part of your documentation that says "here is exactly what the system does in this situation," because that's the part readers actually need to trust.
A Practical Signal
If you're ever unsure whether documentation should be a Gherkin scenario or a wiki paragraph, ask: "Could this be verified by running the system?" If yes, it belongs in a scenario. If it's about intent, history, or design rationale, it belongs in prose.
Pro Tip: When onboarding a new tester, point them at the Gherkin scenario suite before the wiki. It's less likely to lie to them.
Key Takeaways
- Documentation goes stale when nothing forces it to stay accurate
- Living Documentation ties directly to verification, so drift becomes visible (or is caught by automation)
- It complements, not replaces, narrative documentation like wikis and design docs
- Ask "can this be verified by running the system?" to decide where a fact belongs