In my previous article, I discussed the use of Gherkin in writing test cases. Gherkin is designed to test functionality and improve the readability of test cases. But what good is readability if no one reads the test cases? If people continue to refer to outdated documentation (written long ago and potentially not up to date), all that hard work is wasted. In this case, why not combine the specification and test design stages into a single step? This is the idea behind living documentation.
The Importance of Documentation
Having good documentation is crucial for a company: it represents the accumulated knowledge over time and serves as a pillar whenever questions arise about a feature developed months ago (what was the purpose of this feature? What were its edge cases? …).
Documentation outlasts employee departures, preventing the last months of an expert from turning into a race to pass on all their knowledge to others.
Good documentation also facilitates the onboarding of new employees because it:
- Provides a reference for newcomers to consult when they have questions
- Establishes a common foundation for everyone, using the same vocabulary
- Ensures that no important details are overlooked during onboarding
Good documentation also enhances knowledge transfer between teams: everything doesn’t rely on the presence of the expert responsible for a specific feature. This leads to improved efficiency and speed (no need for a meeting if you can just open the documentation).
Documentation can also be a strategic issue. When working on a critical system, regulations often require extremely precise traceability of requirements across subsystems to ensure that:
- No requirements are overlooked
- Every implemented feature meets at least one requirement
The Limitations of Documentation Tools
Companies understand that documentation is strategic, but managing it remains a real headache: it’s an unglamorous task and difficult to maintain day-to-day (we’ve all said, “I’ll update the documentation tomorrow, I have an urgent task right now,” only to forget the next day…).
But that’s not the only challenge! The tools used to manage documentation are often unsuitable, making the task even more tedious. Here are some examples of documentation tools and their drawbacks:
- Flat files (e.g., Word): Unsuitable for maintaining a clear and centralized history (people create copies of files to keep versions, then store them in different locations).
- Ticketing tools (e.g., JIRA): These can centralize everything in one place, but searching through the history is often tedious, tickets are poorly linked, and it’s almost impossible with such tools to have documentation that accurately reflects the current state of the software.
- Wikis: These allow documentation to be well-organized in one place, and keyword searches are smooth. Additionally, we can have a clear idea of our tool’s specifications at any given time. But all of this depends on the team’s diligence and commitment to maintaining the documentation. If the team doesn’t play along, the documentation becomes outdated and therefore useless.
It’s clear that each method has its pros and cons. But one thing is certain: combining all the advantages (up-to-date, centralized documentation with version history) is extremely difficult. As a result, when we need to find information in the documentation, our first instinct is often to throw it all out and start from scratch.
Living Documentation
The goal of living documentation is to have up-to-date documentation at all times. To achieve this, teams must be required to update the documentation through automated tests. Tests are no longer just a gatekeeper before release; they become the specification itself. The tests and the specification are one and the same.
The process of implementing a feature is no longer a waterfall model, where the specification is never updated once the code is implemented:
We move to a format where the code and the specification continuously feed into each other:
To ensure this method works effectively, it is recommended to use the Gherkin language. Gherkin’s readability allows everyone, especially the Product Owner (PO), to be able to update the test cases. Once these test cases are updated, the developer and QA take over to implement the feature and adapt the automated tests, respectively. The documentation, through automated tests, evolves alongside the application’s code, ensuring it never becomes obsolete.
Of course, we retain the traditional benefits of automated tests, such as the ability to detect regressions in the application. The added bonus is that bugs found by automated tests are easier to interpret because the test cases are readable (there’s no need to be an expert in the test codebase to understand what broke).
Given its nature, we can quickly see how living documentation addresses the various issues of traditional documentation tools:
• Centralized documentation within the codebase
• Strong version control thanks to developer tools like Git
• Always up-to-date documentation since specifications and tests are intertwined
Using Test-Driven Development
Test-Driven Development (TDD) is the logical extension of living documentation. Think of it as the cherry on top…
TDD involves writing the tests first, then the feature. It contrasts with traditional development practices where the feature is implemented first, followed by the tests. With TDD, development proceeds in three steps:
- Implement the tests (which should fail since the feature hasn’t been implemented or updated yet)
- Implement the minimal functionality required for the tests to pass
- Optimize the implementation while ensuring the tests continue to pass
There are numerous benefits to TDD, including:
- Tests are always implemented (whereas they are often overlooked in other methods).
- Fewer bugs in the software, as any refactoring is immediately tested.
- Faster coding: This requires some experience and practice, but the code becomes more incremental, and we have greater confidence in it thanks to the tests.
Since the test scenarios are already written when applying living documentation, it’s just a small step to adopt TDD principles…
Constraints and Limitations
I want to clarify that I have never had the opportunity to implement living documentation in a company. While the approach is particularly appealing at first glance, I can imagine there are some challenges in adopting such a practice.
First, it is essential for the tests to be integrated into the Continuous Integration (CI) pipeline. This may seem obvious, but there are situations where tests are triggered by bots (via Slack, for instance) or only by QA teams. If tests aren’t integrated into CI, there’s no guarantee they’ll be run with every code update, and thus no guarantee the specification will be updated.
Additionally, the Product Owner (PO) and QA must work closely together to write relevant test cases from a business perspective, and ones that are easily implementable. This synchronization can be time-consuming: writing test cases in Gherkin is not as straightforward as it seems.
Some living documentation generation tools are too simplistic and don’t allow for easy categorization and hierarchy of tests. As a result, you may end up with an enormous, unmanageable documentation set that’s difficult to navigate.
Finally—and this is probably the most crucial point—implementing a living documentation strategy is a complete paradigm shift: it goes far beyond the scope of the technical team. Its implementation is complex, and the return on investment may not materialize until several months of effort and adaptation.
Everyone needs access to this documentation and should find value in it: POs must learn to write specs in Gherkin; sales teams can use it to draft client tutorials; support teams must learn to navigate it, etc. Moreover, it’s imperative to have top management’s support to embark on such a project!
What about you—have you ever tried or implemented living documentation? Feel free to share your experiences in the comments!