Chapter 7. Living documentation


This chapter covers

  • Understanding living documentation
  • Helping new team members with living documentation
  • Defining domain concepts consistently
  • Documenting product changes and troublesome areas

Everybody who’s ever worked with software has probably dealt with documentation at some point. Documentation can be provided on paper or online, or on digital or analog media, such as audiotape or CDs. SBE introduces a different type of documentation.


Living documentation—Documentation that changes along with the system it describes. Thanks to frequently validated acceptance tests, the living documentation system is aware of changes you make to the system; if the changes yield different results than the results expected by the living documentation system, running acceptance tests will yield an error.

SBE is actually a system of documentation. What I mean is that living documentation is a suite of acceptance tests written in a domain-specific language like Gherkin and readable by nontechnical team members. Through acceptance tests, automated scenarios are tied to application code. This means scenarios that describe functional and behavioral requirements can be used to create a living documentation system that evolves every time the code changes.

7.1. Living documentation in action

7.2. Writing documentation

7.3. Defining important domain concepts

7.4. Documenting decisions using briefs

7.5. High-level overview of the documentation process

7.6. Who creates living documentation?

7.7. Choosing the right audience for living documentation

7.8. Answers to exercises

7.9. Summary