Specification by Example

Chapter 11. Evolving a documentation system

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.

Ideally, a living documentation system should help us understand what our system does, which means that the information must be

• Easy to understand
• Consistent
• Organized for easy ...