concept live documentation in category software development

This is an excerpt from Manning's book Writing Great Specifications: Using Specification by Example and Gherkin. Login to get full access to this book.

Outdated documentation may seem like a reliable source of knowledge about the system, but it only misleads its readers. An automated, frequently tested specification—as well as the examples included in it—is resistant to such problems. The direct connection between scenarios and code often reduces the damage by cultivating a system of living 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.

This is an excerpt from Manning's book Specification by Example: How Successful Teams Deliver the Right Software. Login to get full access to this book.

In the course of researching this book, the most important lesson I learned concerned the long-term benefits of living documentation—in fact, I consider it one of this book’s most important messages, and I cover it extensively. Living documentation is a source of information about system functionality that’s as reliable as programming language code but much easier to access and understand. Living documentation allows teams to collaboratively analyze the impact of proposed changes and discuss potential solutions. It also allows them to make use of existing documentation by extending it for new requirements. This makes specifying and implementing changes more efficient over time. The most successful teams discovered the long-term benefit of living documentation as a result of implementing Specification by Example.

In chapter 3, I introduced the concept of living documentation and explained why it’s important, without discussing how to build it. In this chapter, I cover the practices that teams used to implement a living documentation system.

A living documentation is more than a directory full of executable specification files. To experience the benefits of living documentation, we have to organize specifications so they make sense together and add relevant contextual information that will allow us to understand individual parts.