What is living documentation?

When using Acceptance Test Driven Development (ATDD) or Behaviour Driven Development (BDD) as a development practice you write examples and use them to drive the development. These examples are used as acceptance criteria. They are part of the definition of done. They also support the conversation and help the cross functional team (marketing, product owner, developer, user…) to create a shared understanding of the behaviour of the feature.

So these examples are like documentation. Unlike a word document, this documentation will be always up to date by design. These examples, either automated or not will be executed as acceptance tests before every release.

Hiptest provides a repository to write and share this living documentation across the organisation. The documentation reflects the true state of your project.

The value of Living documentation

First business stakeholders can review the documentation to ensure that it describes the desired behavior of the application. Testers use the documentation as checks to make sure there is no regression. Developers can use this input as a definition of done for their development, making the process very efficient.

Moreover this living documentation is a precious knowledge resource for all the team especially when new people comes in the project. That's a good way to discover the system.

Here is a great examples of a company leveraging the living documentation to transfert the business knowledge of a system.

Parkeon has implemented Behavior Driven Development at scale on a very large project for the city of Helsinki: development of a ticketing system. This project required 4 years and hundred thousands of man days of development. The system is now in production and handles one million commuters per day and 6000 connected devices.

This kind of huge project has a build phase followed by a maintenance phase once the system is live. If, during the build phase Parkeon had 65 full time engineers, for the maintenance phase there is only 5 persons! It was very important for Parkeon to be able to transfer not only the code of the system, but also the business knowledge to the maintenance team. The best way to do that is to transfer documentation using  living documentation. The BDD scenarios that were used at the beginning of the project to define the behavior of the features now  act as living documentation for the maintenance team.

Raphael Citeau, Delivery Manager at Parkeon

 

Adding the context of a feature to the living documentation

Having a documentation always up to date is great but having the context of the features is even better.

At Hiptest we use BDD and living documentation on a daily basis. That's now part of our development process and we have refined this practise. Typically we had the following information to the features and scenarios to extend the living documentation:

• Business assumptions related to the feature
• Current business metrics (usage, activation...)
• Performance

Now every stakeholder, marketing, product owner or developer can look at a feature, understand the behaviour, get feedback from the production and measure the impact of the feature in real time! That's the value of living documentation.

We use the following stack: Hiptest, Shippable and Intercom but of course they are many other options.