What are the benefits of a Living Documentation?

Most people will agree that software development has a lot to do with technology. I’m one of those people. I’m also one of those people who agree that successful software development has a lot to do with good tools. Are you one of those people as well? Then I’ve got just the thing for you …

This thing is called a living documentation. As a longtime maintainer of Pickles, the open source living documentation generator, I have some experience in how to profit from it. SpecFlow also offers a Living Documentation tool called LivingDoc. It’s free to use and has the power of a commercial company behind it.

What can a living documentation do for you? I’ll give you a few examples, taken from the life of my fictional software development team.

Russell, Product Owner

Meet Russell, the Product Owner. He is responsible for understanding the requirements of the customer, and for “translating” them into something the developers and testers understand. He has no trouble understanding the customer – he used to work in their line of business himself.

The challenge lies in making the developers understand.

That problem has mostly been solved by using Behavior Driven Development (BDD) and writing acceptance criteria in Given-When-Then (GWT) scenarios.

That gave rise to another challenge: how to keep an overview of all these scenarios. To be honest, that is just a different form of the question “how to keep an overview of the backlog?”. There are several tools to manage a backlog of user stories, and they all have their own solution for “keeping an overview”.

Russell solves the problem of “how to keep an overview of the scenarios” by using a living documentation. It contains all the features with all their scenarios, nicely structured in directories. The search function helps him to quickly locate scenarios, even if he remembers only one or two keywords from the feature.

The developers like the scenarios, but Russell prefers to add some background information: text, some bullet points, or – his favorite – an image. Russell firmly believes that an image says more than a thousand words. The living documentation nicely shows this background information, including the image.

In sum, the living documentation provides Russell with a reference of the requirements. Thanks to the included test results, he uses it as a progress report as well. The test results who which scenarios are passing – and the more scenarios are “green”, the closer the project is to completion.

Russell also likes to use the living documentation when discussing requirements with the customer. The scenarios are an excellent way to start a conversation, but the customers can’t be bothered with technical things like Visual Studio (Russell doesn’t fancy Visual Studio either, to be perfectly honest). The customers are used to online documentation, however, so Russel presents the scenarios using the living documentation.

All in all, there are several aspects where Russell uses the living documentation because it makes his work as a product owner smoother.

Damian, Developer

Meet Damian, software developer. He likes to read acceptance criteria in the form of GWT scenarios: they are much clearer and less ambiguous than other formats (he especially dislikes the “if … then … but if … then …” format of acceptance criteria). While working on a user story, Damian prefers to write the automation layer for the scenarios first. That gives him some clues about how to design his domain model and helps him to stay on track.

He adds only those features to the domain model that he needs for the automation layer. The more scenarios turn green, the closer Damian is to finishing the user story.

Damian likes to check the living documentation at least once a day, usually in the morning. The living documentation is included in the build process, so whenever a build is run, a new version of the living documentation is produced. The nightly build includes all regression scenarios, and the living documentation shows the results of those scenarios. When a scenario fails, the exact step where the problem occurred is highlighted. By expanding that step, Damian sees the error message. That gives him a starting point for the bug hunt, saving him the trouble of digging through endless logs to find the exact place where the error first showed up.

Damian has saved a lot of time, thanks to that particular feature of the living documentation.

Floor, Tester

Meet Floor, the tester. She’s always a bit at the end of the communication food chain, forever trying to keep up with the latest changes the developers and the product owner are discussing.

She’s grateful that they use BDD, which makes sure that the developers and product owner write their newest versions in a structured way.

Floor’s job is to create and execute test plans, and one thing she wants to avoid is including test cases for aspects that are already covered by developers when they automate the GWT scenarios. She needs to know which scenarios are automated very well. By convention, Russell, Damian and the other team members tag scenarios that are intended to be automated and those that will not be automated.

Floor likes to use the living documentation to find those scenarios: the living documentation can filter scenarios by tags. Using that functionality, Floor finds the scenarios she needs to devote special attention to.  As a tester, Floor has access to a variety of tools. Some of them are almost as powerful as Visual Studio, others are more light-weight. The living documentation is one of those light-weight tools, and it helps her to find the scenarios she needs much quicker than the more powerful tools.

Conclusion

A living documentation is one of those rare tools in software development that offers something of value to all three roles in BDD – Product Owner, Developer and Tester. Russell, Damian and Floor all benefit from having a living documentation, having a smoother and faster workflow.

Evolve your documentation with every new build

Generate living documentation and reports that can be easily shared with your team, without the need for Visual Studio – for free, no license costs

➡️ Try out SpecFlow+ LivingDoc