Living Documentation – the beating heart of BDD

BDD comes with many advantages, like: business readable test cases (… whoops I meant scenarios!), tight alignment between scenarios, requirements/specification and code which leads to less outdated assets, it also encourages specification and testing to be a team activity where all agile roles play a part which in turn generates the buy-in necessary to achieve in-sprint automation and to make automation part of the definition of done.

Having a strong (test) automation strategy then leads to higher pipeline throughput, faster turnaround on application functionality, much needed speed to market and confidence to release. Which is the exciting part for any business stakeholder. But these are all things we as experienced BDD users know already and have been the reason for us to implement it in the first place.

But what happened to the idea of Living Documentation that Gojko Adzic has elaborated on in his book Specification by Example. Are you taking advantage of this powerful concept yet? I collected some questions that our community has been asking us over the recent weeks in a Q&A section at the bottom of this article. But first, let’s take a look at how Living Documentation can look like based on Specflow+’s LivingDoc Generator.

Specflow+’s LivingDoc Generator generates a view of all your feature files right from your GIT repository. It allows you to view them, filter them, read through the scenarios. A great way to review what the application already does or for just zooming in on the features that are new and have just been built/changed. Something you may want to pull out before you start your demo to your team members and stakeholders. It is a current, browsable documentation of your application functionality in one single place and at once glance.

💡 Demo: Try out our SpecFlow+ LivingDoc Generator Demo which is hosted on GitHub Pages.

You can also connect it with your test execution and overlay it with the test results of automated scenarios. This will allow for better release decisions and to immediately identify the functional gaps of your current application build. The beauty of this is that it establishes the closest possible tie between application status and application behavior/functionality. In a way the documentation becomes alive and you know exactly in which functional state your application currently is.

This ever-evolving artifact, therefore, resembles all BDD stands for. It brings all aspects of BDD together and bundles them to allow for yet another way of gaining value from it. It is the living proof of a team truly applying all aspects of BDD from Discovery, to Formulation, to Implementation and Automation. It serves as the cockpit for teams from planning a feature all the way to testing it. Which is why I consider it the beating (evolving) heart of BDD.

What is the value of an auto-generated validated Specification?

We all have faced situations where we quickly needed to find out how a specific feature is supposed to work. We go into our technical documentation, we read through our tasks and backlog items that were related to this functionality, we play around with it on the live app or open the code to find out what it does. Depending on how well you are managing change to your application you may only need 1 of these sources or all of them combined. Generating specification that is automatically validated (by test results) won’t allow you to get away with undocumented change and is a fast and easy way to find out how the application is supposed to behave.

What situations does it help in?

  • Planning for changes of your code
  • Support inquiries
  • Functional reviews of any kind (auditors, project sponsors, stakeholders, …)
  • Training/Onboarding of new team members
  • Tracking implementation progress/status

Is it truly readable/interpretable by anyone?

Gherkin syntax is intuitive for users with technical affinity (Developer, Tester, …), still structured enough to capture complex situations and approachable enough to bring in users (PO, PM, Stakeholders) that are not extremely used to communicate in a set structure. It might take a few tries until users become fluent in authoring but reading it typically goes very quickly. These are main reasons why Gherkin became popular and are a good reason to leverage it also for documentation purposes.

Does it really stay up-to-date all the time?

This question comes down to BDD maturity. If your team applies BDD consistently and defines behaviors and scenarios across the board so that every work item manifests itself in at least a scenario/changed scenario your Living Documentation will always be accurate and up-to-date. Implementing Peer-Reviews and adding BDD scenarios to the Definition of Done may help reaching this maturity.

Is it the best way of dealing with requirements/system behavior documentation?

Leveraging acceptance tests with features and scenarios for behavior documentation re-uses assets that the team needs to create anyway to ensure proper implementation. Version controlling the feature files alongside the application code helps with the challenges of keeping specification and tests in sync with code. This makes using this concept for system design documentation incredibly efficient.

Isn’t this just a test report?

No. Clearly not. Living Documentation explains your actually implemented system behavior leveraging the assets created along the way (feature files). The overlaid test results confirm that the specification is actually up-to-date and accurate. This allows for a quick but comprehensive view after each build. Living Documentation is not intended for debugging or putting analytics on top of test runs.