Living documentation from multiple repositories
BDD | Posted May 01, 2020

The days when all applications were monolithic, living in a single source code repository, are over. Today, the majority of applications are layered, include multiple services, are written in several languages, and are deployed on heterogeneous platforms. Often, the source code for each component lives in a separate source code repository and each component has its own build and deploy process. This leads to nightmares when it comes to reporting across all the components that make up the application.

A close up of a logo

One of the benefits of Behaviour-Driven Development (BDD) is that, once the team has discovered the relevant examples to document the application’s expected behaviour, that documentation can be automated, making it living documentation.

Living documentation – documentation that automatically informs the team when it diverges from the implemented behaviour of the application.

Teams following a BDD approach then face the challenge of creating a single source of living documentation that encompasses all of an application’s components. All too often, it requires handcrafting scripts to copy Cucumber’s HTML/JSON output from each component’s build to a shared place in the company’s intranet. This is work that we’d prefer that we didn’t have to invest development and maintenance time in performing.

Cucumber for Jira to the rescue

Cucumber for Jira (C4J) has recently released a new feature that pulls together living documentation from multiple repositories into a single Jira project.

A screenshot of a cell phone

Adding documentation from a new repo is as easy as:

  1. Choose your source control provider (GitHub, GitLab, and Bitbucket are the currently supported cloud providers)
  2. Choose the repository that the documentation should come from
  3. Choose the branch that you want to work from
  4. Repeat to include documentation from as many repositories as you need

What makes this living documentation is that anyone reading it can immediately see where the behaviour of the application has diverged from the documentation. The green ticks indicate that all the scenarios for that feature have passed – so the documentation and application are in sync. A red cross indicates that one (or more) of the scenarios for that feature have failed.

You can drill into any feature to read the scenarios and, if there are failures, see what went wrong:

A screenshot of a cell phone

No more additional complexity to maintain in your build scripts. No more scrabbling around looking for the right documentation. No wondering whether the documentation is correct and up to date.

What are you waiting for? Try this out for free, right now!