liveBook · Manning

Living documentation

As explained in Effective Behavior-Driven Development

Living documentation is documentation kept aligned with the current behavior of a software system through executable or continuously validated specifications.

A specification can become outdated as soon as the software changes. Living documentation addresses that problem by expressing expected behavior in business-readable scenarios and running those scenarios against the system. When a scenario fails, the team is alerted that the documented expectation and implementation do not agree; the failure does not, by itself, say which is wrong. section 6.4 section 1.3.4

Investigate a mismatch before changing either side:

  • If the behavior is planned but not implemented, implement it when appropriate. section 6.4
  • If the implementation is defective, fix the code and rerun the scenario. section 1.3.4
  • If the expectation is outdated or contradictory, correct the scenario or resolve the contradiction. section 1.3.4

Creating it is collaborative work, not just test automation. Discovery produces examples; formulation turns them into readable scenarios; automation checks them. Keep the resulting rules and scenarios organized by coherent product functionality rather than by short-lived user stories, so readers can find what the system does after a story is delivered. section 1.7 section 10.1

Listing 10.1 Structure of the blocklisting feature file (scenario steps omitted for brevity)
Feature: Blocklisting

Rule: Don't offer pay-on-collection for restricted customers
  # Two scenarios merged, because authentication is incidental
  Scenario: Restricted customer is not offered pay-on-collection option

Rule: Customer's email OR phone must match those on blocklist
  Scenario Outline: Decide if customer is restricted

Rule: Restrictions are independent of authentication status
  Scenario: Unauthenticated customer is restricted
  Scenario: Authenticated customer is restricted

Rule: Blocklist is manually configurable
  @manual
  Scenario: Upload replacement blocklist

A blocklisting feature groups scenarios under business rules, such as whether a restricted customer is offered pay-on-collection. The grouping makes the documented behavior easier to navigate than a file for each delivery story. section 10.1

In a fixed-scope project, continuously validated scenarios can make decisions explicit where a static specification may already be stale. In a regulated project, versioned scenarios and execution reports can link expected behavior, checks, and results for a particular product version. Such reports still need preparation for formal requirements, and other documents may remain necessary. section 4.6 section 4.7

How Effective Behavior-Driven Development covers it

How deep it goes
Explains the discovery-to-automation path, failure causes, investigation, and organization by functionality; leaves scenario automation details for later treatment.
Examples
Uses a blocklisting feature organized by rules and scenarios, plus fixed-scope and regulated-project documentation needs.
What it assumes
Introduces living documentation through the basic discovery, formulation, and automation sequence without requiring automation code first.
What you can do after
Practice/perform investigation of failed scenarios and organize enduring rules and scenarios by product functionality.
How it connects
Connects behavior-driven development, discovery, formulation, scenario automation, user stories, and feature files.

Also explained in

Compare how 4 books explain living documentation →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Effective Behavior-Driven Development. The section links point to the parts of the book it draws on.