BDD Living Documentation | Working with BDD Remote: Part 3

In the article series so far we have seen how to get a better understanding of the requirements using examples in a remote environment and how to formulate these into BDD scenarios online. We also mentioned that the documentation we produced this way is a living documentation, because the scenario execution results can immediately alert when there is a conflict between the expectations and the implemented system. But how valuable is the documentation if nobody uses it? In this section we are focusing on how to make our living documentation better accessible to all stakeholders. In a remote environment this is particularly important.

When everyone is in the office, information sharing is easier. We can ask the colleagues sitting next to us and we are surrounded by information radiators: team and task boards, posters, or large screens with the system status. Obviously we also have more opportunities to use informal communication channels. In pre-COVID-times I learned the most during the coffee breaks.

Information is available in a remote environment as well, it is just harder to get it. We can ask our colleagues in our chatrooms or at the next meeting, but any piece of information that is available and easily accessible improves the information flow significantly.

Imagine the following situation: you are a tester working from home who would like to perform an exploratory session on the search features of the application your team is developing. You remember that the team has made some changes on the search so you need to check whether this has been finished already or it may affect the area that you are going to test.

The story can continue in different ways:

1. The team created BDD scenarios for the search changes. You remember that the link to the test execution report was mentioned in an email somewhere, so first you try to find the email thread with the link. The link does not open, because of wrong security settings, so you need to fix those first. In the report you find that the search change scenario is still failing, but unfortunately, the report contains the scenario title only, so you cannot check if it is related to the area that you would like to test. The full scenario is in a separate git repository. You find and clone the repository. The tool you use to edit the feature files needs to perform an important update, which takes a couple of minutes, but finally, you are able to find the feature file where the failing scenario is documented and you can check the scenario steps. Good news, they are not related to the thing you wanted to test, so you can finally start the exploratory testing session. (If you still remember what you wanted to do originally.)
2. The living documentation is available linked from the project dashboard, so you just open it in your browser and check out the search-related scenarios. You filter the list for the scenarios that are currently failing that show you the scenario the team is working on. You check the scenario, but luckily it is not related to your exploratory testing goal, so you can start with it immediately.

As you can see, the same information was available in both cases, but in the latter one, the actual work could be started earlier, as the information was available promptly. The difference in efficiency is clearly visible, but how many times have we experienced the first ending! It is a high time to fix this!

As you have seen from the example above we could (and should) distinguish between where and how the scenarios are captured and how you distribute the (read-only) results to a broader audience. Providing an easy-to-access read only platform for your living documentation is easier to achieve and it can provide significant value, so it makes sense to focus on that.

The exact steps and tools to be used for making the living documentation accessible depend on the platform and the tooling you are currently using. Based on a recent survey conducted by Gojko Adzic, most of the teams integrate the living documentations to the ALM tools they use (e.g. Azure DevOps or Jira). This is an aspect of BDD that is currently still under heavy development, so depending on the platform you use, you might need to do a bit of plumbing, but the efforts pay off quickly.

It is not our goal to list all possible tools and libraries that can help to make your living documentation accessible; let us just mention a few ones that are more commonly used. (The tools are listed in an alphabetical order, there are both free and commercial tools among them, check their exact licensing conditions for details).

For Azure DevOps:

• SpecFlow+ LivingDoc renders feature files in Azure DevOps with filtering and linking capabilities
• SpecSync for Azure DevOps synchronizes scenarios and their results to test case work items

For Jira:

• Behave Pro integrates the BDD process to Jira including scenario editing, living documentation and related exploratory testing
• Cucumber for Jira allows you to capture scenarios and visualize them as living documentation

General purpose tools:

• Augurk can be used to self-host a dynamic living documentation system
• CucumberStudio has an integrated BDD platform that focuses on collaboration, automation and living documentation
• Gherkin is an open-source library that allows you to parse feature files and build your own project-specific tooling on top of that (available for many platforms, including .NET, JVM, JavaScript)
• Pickles Doc can render feature files with test results to HTML that you can publish to your project dashboard

Conclusion

In this article series we have been focusing on how to improve collaboration using Behaviour Driven Development in remote environments. Our goal was to share a few ideas on how the teams can better understand, document and verify business requirements with BDD, so that we can keep our efficiency with distributed online teams, where the possibilities for communication are limited.

We have seen how examples can help to have a better understanding and how we can capture them in online requirement workshops (part 1), sometimes also called discovery sessions. At these meetings we wanted to use our shared time efficiently, so we captured the examples in a simple form, not using Given/When/Then (part 2).

Once we got a solid shared understanding, we wanted to document the examples to BDD scenarios in Gherkin format, so that we can verify our implementation by automating them, but also because we wanted to build up a comprehensive living documentation.

Finally in part 3 we focused on the accessibility of our results. The value of the living documentation is limited if we cannot make it easily accessible for all stakeholders. This is where tooling can help. While the exact tooling and their integration probably needs some effort, it is a valuable investment. We have listed a few tools that can be considered, but we encourage you to do further research focusing on your own context. Feel free to share your findings in the comments section below.

We live in a difficult time and it is up to us how we can get the most out of it. Stay safe, but keep collaborating.

Gaspar Nagy is working as a BDD trainer & coach. Check out his public BDD with SpecFlow, BDD Vitals or BDD with Cucumber courses or request an in-house private course for your team. He is a BDD addict and as such he’s editing a monthly newsletter about interesting articles, videos and news related to BDD, SpecFlow and Cucumber.