Living Documentation
What is Living Documentation? How do I make sure I handle documentation correctly?
Have you ever watched the gameshow Jeopardy!? For anyone out of the loop, the host provides answers, and contestants win points by guessing what the questions are.
Let’s have a quick round now: the answer is “I don’t know” – what is the question?
If you’re in the world of software engineering, the question might be one often asked by developers to stakeholders: “Is the software supposed to do that?”
Documentation? What Documentation?
The problem with software is that as it grows, it becomes more complex and nuanced.
Early in an application’s life, it may only have a limited subset of features and a single type of user – with the functionality afforded to said users being obvious. Obvious enough that it doesn’t need to be documented, right? After all, the Agile Manifesto states:
“Working software over comprehensive documentation”.
But as the features grow, conditions, access and functionalities expand, while obviousness reduces.
For example, a new type of user could be needed, with entire sections of functionality becoming their sole domain. Or maybe some background functionality gets added, such as a weekly report for managers that’s automatically generated and sent via email.
Surely now this is justification enough for developers to stop coding and start writing some docs, but they’re already under pressure to get the new features ready in time for the press release, and this is still obvious, right? I mean, they don’t remember exactly which managers get the report, but it’s all there in the code, and they’ve got more important things to do.
The problem is that far too many applications simply lack the documentation which explains what the features are supposed to do. And even if the developer who wrote the software is still on project, memory is a fickle thing, and it’s far too easy to misremember important details.
And what if the original developer leaves the project? All the knowledge they had locked way in their brains is taken with them.
A Lie Waiting To Happen
But there is one thing worse than missing documentation, and that’s incorrect documentation. It may have been correct at one point in the past, but as the project evolves, it becomes a lie waiting to happen – something increasingly prevalent in the fast-paced world of agile development, as enhancements and tweaks are made to the codebase.
So, if even one tiny section of documentation becomes untrustworthy, it undermines the credibility of the rest of it, which damages trust. Suddenly it becomes more reliable to spend hours looking at the code, rather than the minutes it should take to look at the documentation.
Scary thought – let’s play another round of Jeopardy! to calm our nerves.
This time, the answer is: “A method which makes documentation a naturally occurring artefact and guarantees that it is always correct and up to date”.
What is Living Documentation?
Living Documentation is one of the many benefits from following the Behaviour Driven Development (BDD) approach to software development. I’m not going to spend too much time explaining BDD, other than to quote Wikipedia:
“[BDD is] an agile software development process that encourages collaboration among developers, quality assurance testers, and customer representatives in a software project.”
Our route to Living Documentation starts with a Three Amigos meeting (so named because it involves a representative from each of the three disciplines listed above) in which we perform an exercise called Example Mapping.
This involves discussing the software requirements from the perspective of the end user and establishing the rules which need to be met by the software. We find ways of proving the rules by listing concrete examples wherein they’ll be exercised, and document it all using a human-readable language called Gherkin.
For example, one rule could be that a confirmation dialogue needs to be shown before a record can be deleted. This would be represented by a .feature file which looks something like this:
Feature: Educator deletes school
Rule: An educator must confirm deletion before a school is deleted
Scenario: the one where they confirm deletion
Given an Educator is on the school profile page
When they press the "Delete school" button
And they confirm the "Are you sure?" dialog
Then the school is deleted from the database
Scenario: the one where they don’t confirm deletion
Given an Educator is on the school profile page
When they press the "Delete school" button
But they dismiss the "Are you sure?" dialog
Then the school is not deleted from the database
As you can see, Gherkin is very similar to plain English, and is understandable even without technical knowledge. It sets out a real example of how the software should work, including what should happen in every possible outcome, letting the development team know what they need to code, the testing team how to verify it’s working, and the customer representatives how to support it.
But Wait, There’s More
This is all very impressive, but we’ve not got to the best bit yet.
You would have noticed that Gherkin uses slightly unusual formatting and a set of specific keywords (Feature, Rule, Scenario, Given, When, Then, And, But). These allow the development team to hook into the steps defined and write test code which automatically performs the action described at the press of a button.
This means that at any point in the development process, an automated test run can be performed, which will either prove the software still function as intended or send an alert to the development team telling them exactly what is broken, letting them go in and fix the problem.
As I’m sure you can imagine, this is a very powerful feature, especially for large teams, as it means changes can be made to the code, safe in the knowledge that if anything gets accidentally broken, the developer will be alerted, letting them fix it right away.
Living Documentation means you can see at a glance what the software is supposed to do, rather than combing through the code to back up a hunch.
We’re big fans of the Behaviour Driven Development approach here at Foxsoft, and would love the opportunity to prove its benefits to you, so if you’d like to work with a team that can deliver, we’d love to hear from you.