A requirements document can say what a feature should do while the running application does something else. Living documentation closes that gap: executable specifications record agreed behavior, automated tests check it, and readable results show whether the application meets it. The term can mean the executed feature files or the reports generated from them. section 7.6.1 section 16.1
The starting point is a conversation, not a report generator. Stakeholders, analysts, testers, and developers agree on concrete examples, then express them as scenarios in the language users recognize. A Given–When–Then scenario can become an automated acceptance criterion; its result reports on a requested feature rather than an obscure test method. section 7.1 section 16.1
To keep the documentation useful:
- Run the specifications against the application, preferably with each build. A passing scenario supports the documented behavior; a failure exposes a difference that needs investigation. Do not treat an unexecuted feature file as proof of current behavior. section 7.6.1 section 16.1
- Write scenarios as clear business examples, not brittle test scripts. Include enough detail to make the rule meaningful without burying its purpose. section 7.0 section 7.6.1
- Organize reports for their readers. Group features by capability or epic to show the requirements hierarchy; use tags to focus a view on a release or iteration. section 16.5 section 16.5.3
A change request becomes a checked example
Suppose a journey planner currently proposes the next two trains, but users now need four. Update the acceptance scenario to expect four departures and run it: its failure demonstrates that the application has not yet met the new request. Update the corresponding unit test and implementation, then run the checks again. The scenario remains a readable example of the changed rule. section 3.7
Scenario: Next train going to the requested destination on the same line
Given the T1 train to Chatswood leaves Hornsby at 08:02, 08:15, 08:21,
8:34, 8:45
When Travis wants to travel from Hornsby to Chatswood at 08:00
Then he should be told about the trains at: 08:02, 08:15, 08:21, 08:34
This revised train-departure scenario makes the new four-train expectation visible in the same format used to check the application. section 3.7
Reports serve different decisions. Business stakeholders can confirm that delivered features match their needs; testers can use the results to guide exploratory testing; developers can inspect existing behavior before changing it. Passing and pending acceptance criteria also make progress visible. Release-focused reports can show what was scheduled, how it was tested, and how ready it is—but passing acceptance tests need not replace exploratory testing before release. section 16.0 section 3.6
The same principle applies below the feature level. Readable unit and integration tests can document how code behaves through working examples; clarity matters more than elaborate reporting. When requirements change, update or remove specifications that no longer apply. When a change breaks a still-valid specification, investigate a possible regression. Documentation stays living because the examples are maintained and checked, not merely because they are stored beside code. section 16.5.4 section 2.3.9
