Living documentation is documentation that is set up to be continually updated - and is something that can be critical for the continuity of your Drupal project.
Having living documentation might not initially seem that important. Generally documentation is most useful when you're looking at someone else's work, having your team spend time continuously documenting their own work, when they know it so well, can seem like a waste of time and effort.
So, why make the effort to produce living documentation?
Change management
I'm going to base this article on the scenario that you employ a new Drupal developer, or in a more extreme case change the development team completely.
So now all of a sudden someone new needs to work on your Drupal project, who in this case we are going to imagine works completely differently to the original developers in a variety of ways:
- Development workflow (Scrum vs Agile vs Waterfall)
- Build patterns
- Delivery process
There's a lot of learning that needs to be done on both sides in order for the client to work efficiently with the new developer or team.
The pickle
Now, without living documentation, we would be in what I would describe as a 'bit of a pickle'!
The old developers start to put together some docs on how the project was built - but how much of the project's features can they really describe accurately and efficiently considering they may have limited time or availability, and they may have not looked at these features for a long period of time.
Maybe we are fortunate to have an archived of good user stories and well defined tasks, but the bottom line is that it can get quite confusing rather quickly.
Especially when one document points to another, and the developers need to cross reference inormation to work out what the objective of a feature was.
There's also the effects of perception, clients and developers usually have conversations to clarify details of these type of documents, which often don't get added to the documentation, so without those explanation the developers could come up with conclusions that are close but not quite right.
Specification by example to the rescue
With Specification By Example all of our time invested in documenting the site is done in our discovery phase when we are defining what it is we are going to be building. So yes, that does mean you spend more time defining your spec, but it can mean you save a lot of time in your development and maintenance phases.
When using Specifications By Example, in the form of Behat features, the test suite that is produced provides the living documentation for a project.
So what's the benefit?
So to summarise the benefits of setting up living documentation, there's no need to invest time at the end of a Drupal project documenting the site, instead you can carry on producing features your project needs.
You end up with a clear specification by example in the form of automated Behat features. So not only can the new developers quickly see what it is the feature should do, but also see the way you tested it, which will also give them a more in depth understanding of the feature's details.
Clients and developers have already signed off on this documentation when they sign off on the spec during the discovery phase, so there's one less meeting to worry about.
Finally the biggest benefit is the fact that it is living documentation. The specs will be kept up to date naturally, and due to their format they should not require much, if any, conversation to understand.
If you found this article interesting why not take part in one of our Quality assurance training courses which cover the topic in more detail.