What’s the only thing scarier than zombies? If you ask most developers, it’s keeping up-to-date documentation. If you ask us, we’d say a lack of documentation is much more terrifying.

While you might not agree either is actually more frightening than the living dead, there is something to say about how unsettling it is when we let documentation die.

“A lot of times teams get the beginning and the ending of BDD wrong, so they don’t focus on communication on the front-end and they don’t focus on the end result for living documentation, they just focus on the middle automation piece,” noted Joe Colantonio in his recent episode of TestTalks featuring HipTest Co-founder Laurent Py.

However, when we dismiss these bookends of communication and documentation, much of the value of Behavior Driven Development (BDD) gets lost in the noise of constantly changing software. Fortunately, living documentation will also help your team practice better collaboration in BDD.

What is Living Documentation?

What do we mean by living documentation in the first place? It’s an up-to-date record of a feature that defines test scenarios through a common language. This way all team members can have current and accurate information of the application in production, as well as an archive of past tests for reference.

But don’t confuse living documentation with test reports. While test reporting records the results of automated tests after they’ve passed or failed, living documentation is written before development starts in order to decide how a feature should behave according to requirements. It’s decided on by multiple team members and written collaboratively.

As teams get on board with Agile and DevOps and adopt CI/CD methodologies where they’re iterating and releasing at rapid speeds, accurate documentation becomes extremely important. Moving at high velocities means that code is always changing, which can be difficult to keep track of.

Additionally, living documentation is a pillar of encouraging collaboration within teams that practice BDD. By putting documentation into a common language, it bridges the gap between business and technical team members.

In this way, living documentation can be referenced among product, business users, test, and development. In fact, it can even prove useful for support teams, customers, and new team members. Once you have solid documentation, you’ll find that it gives you the intelligence to effectively communicate with various team members and create a clear vision for the future design of the application.

A big reason why documentation goes usually ignored is that, well, writing documentation isn’t very fun. We’d all much rather be building out a new feature than writing about what it’s supposed to do. But the best thing about living documentation is that it’s a painless process that shouldn’t take up much -- if any -- extra time.

How to Get Living Documentation

In BDD, you’re already writing automated tests in plain English with Gherkin through executable specifications. This means that your tests also serve as documentation. Because it’s defined by your automated test suite, the documentation is “living” in the way that it’s always up-to-date because it’s generated from tests that are executed as part of the CI/CD pipeline.

There are two ways to create living documentation. Like most things in testing, you can go the manual route or the automated route.

In order to manually create living documentation, the person creating the scenarios must diligently record them each time in order to keep an accurate and up-to-date record. You need software like Microsoft Word or Google Docs to keep this information in a format that’s easily accessible by all team members or stakeholders.

Unfortunately, oftentimes documentation efforts start out strong and fade out over time. When your tests are running as part of a CI/CD pipeline, it’s much more practical and efficient to have living documentation generated automatically.

HipTest does just that, taking your test scenarios and turning them into living documentation so you can view the history of your application at any time.

Go back in time to look at the evolution of different features, or get a read on how they currently work in production. Because the living documentation is aligned with code and updated according to your CI/CD pipeline, there’s no beating the accuracy -- and it comes with no extra work to maintain.

Additionally, rather than locking away this documentation in your Git repository, HipTest enables you to share it with your entire team through an easy-to-use web application, which integrates with GitHub, GitLab and Bitbucket.

[embed]https://www.youtube.com/watch?v=bVIVHQbvfHw[/embed]

At the end of the day, living documentation is nothing to fear. In fact, it just might make your life a little easier.