What makes a scenario report generated from the last run 'living documentation'?

### What the phrase actually claims **Living documentation** is a description of a system that is *generated from artefacts that execute*, rather than written and maintained by hand. In a behaviour-driven setting those artefacts are the scenarios: business-readable descriptions of behaviour, each attached to automation that drives the real system. A publishing step takes the last run of that suite and renders it as a document — one page per feature, each scenario shown with its steps and the status the run gave it. The word *living* is doing precise work. It does not mean "frequently updated". It means the document has no independent existence: there is no source file a person edits to change the published text, and no version of the text that can be right while the system is wrong. If someone changes the behaviour and does not change the scenario, the scenario fails, and the corresponding page in the published document renders red. The documentation does not quietly drift out of date — it *breaks loudly*, in a place people are already looking, on the same build that introduced the change. ### The mechanism, step by step 1. Scenarios live in the same repository as the code, in business-readable text. 2. A run executes them against a known revision of the system. 3. The run emits a machine-readable result per scenario: passed, failed, or not executed. 4. A generator merges the scenario text with those results and publishes an artefact — usually a static site — stamped with the revision, the timestamp and the environment it ran against. Every property people want from living documentation comes from step 3 being real. If the report is generated from scenario text alone, with no run behind it, it is a prettier wiki page: it can be as wrong as any hand-written page, and nothing will say so. ### A worked example A four-person team owns a parcel-tracking gateway. Their published specification says: *Given a parcel has been scanned at a depot, When a customer requests its status, Then the response shows the depot's city and the scan time.* Someone adds a cache in front of the status lookup, and under a particular expiry path the gateway serves a stale-cache read: the previous depot, minutes after a newer scan. The scenario fails on the next run. The published page for parcel status now shows a red scenario with the failing step highlighted — so the document is announcing, to anyone who opens it, that the system no longer does what it says. A hand-written page describing the same behaviour would have stayed confidently, silently wrong for as long as nobody re-read it against the code. ### What it does *not* give you Three honest limits are worth saying out loud in an interview. **Completeness.** A green report documents the behaviour that has scenarios. It says nothing about behaviour nobody wrote a scenario for. Reading a fully green specification report and concluding "the system is fully specified" is the single most common misreading of the artefact. **Readability.** Generation guarantees the document is *accurate about the scenarios that ran*. It guarantees nothing about whether the prose is comprehensible to a reader outside the team. That depends entirely on how the scenarios were written, and it degrades quietly as scenarios accumulate incidental detail. **Audience.** A generated artefact that nobody outside the team ever opens is a build cost, not a documentation strategy. The generation is cheap; the discipline of keeping hundreds of scenarios worded for an outside reader is not. ### Why interviewers ask it It is the clearest articulation of what behaviour-driven work buys that ordinary automated tests do not. Automated checks and living documentation are the *same artefacts read by different audiences*: the team reads them as a regression signal, everyone else reads them as the specification of record. A candidate who can state that duality — and then name what it does not cover — is showing they understand why the business-readable layer is worth its translation cost, instead of reciting a slogan about executable specifications. ### How to answer well Lead with the mechanism ("generated from a run, so it cannot disagree with the system without failing"), contrast it with the failure mode of hand-maintained documentation (silent staleness), and close with the limit (green means *these* scenarios pass, not that the system is fully described). If you have published such a report in practice, mention what you stamped on it — the revision and the run time — because provenance is what turns a rendered page into evidence.