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 access
In this chapter, I present the techniques that the teams from my research used to fulfill those three goals.
By rigorously refining the specification, as described in chapter 8, we create executable specifications that are focused and self-explanatory and make use of the domain language of a project. As a living documentation system grows, we add information to its specifications and merge or split them. Here are some useful ideas for keeping the living documentation easy to understand as it grows.
