Why you need living documentation for software projects (and how to do it)

Documentation is often the most neglected area of software projects. It can be time-consuming and sometimes tedious, and keeping on top of it can often feel like a chore. Good documentation communicates effectively, without being a maintenance burden.

The trick is not to create documentation for documenting’s sake—it needs to add value. Teams will not want to do it if it isn’t useful.

One of the aims of the Agile manifesto reminds us to favour:

“Working software over comprehensive documentation.”

This aim does not mean you should throw documentation out the window as it might initially seem. The intent is to reduce wasted effort by only documenting what is necessary and useful to help share knowledge.

What is living documentation?

Living documentation is documentation that evolves by itself with minimal effort. Automation is usually involved in creating and keeping the documentation up to date. The term was coined in the book Specification by Example by Gojko Adzic. He explains how teams realised that automated requirement tests (executable specifications) could easily become a specification document. Later, we will give more ideas of other things you can automate.

Why might you need it?

Some of our clients have told us that documentation can be a puzzle for them. They think they would like to try it, but don’t know how. Or they don’t have an effective process for creating and maintaining it. We believe living documentation is the missing piece of the puzzle. You might have worked on projects where:

• Documentation is neglected or non-existent. Teams might say they don’t have time to do it. You might even have heard, “our code is so obvious we don’t need to document it.” This might be true for simple codebases, but it makes assumptions about other stakeholder’s needs and the knowledge of whoever maintains it.
• Updates are a chore. Manual updates can be time-consuming, and admittedly, sometimes dull.
• It quickly becomes out of date. If it is not current, documentation is less valuable, ignored, or feels like a waste of time.
• Changes to documents take time to approve. Especially if files are large. Minor differences can be hard to spot, and you could end up with lengthy “draft” documents or multiple working versions. Developers risk working from incorrect or outdated information.
• Tools make life more challenging. Sometimes our clients have found that tools work against them. They might not easily highlight or track changes or versions. Updates might cause cross-reference mismatches or allow accidental changes of things like requirement numbers.
• An entirely different team does the documentation. In this case, the people who could gain the most value from it are less involved (if at all). The docs created will be less relevant and have less value.

Why would you want GOOD documentation?

You want useful documentation that adds value for those that use it. The best documentation helps teams with communication and alignment, and is both valuable and low maintenance.

Good documentation helps development teams to know what is happening with the project and how it should work. It allows stakeholders to have clear visibility and oversight. It is accessible and becomes the first place they look for answers. If you need auditing, it also makes it easier for the auditor to find everything and understand how the project and team works.

In the book Living Documentation by Cyrille Martraire, there are four principles of good living documentation. It should be reliable, low effort, collaborative, and insightful.

Reliable

It co-exists in the source control with the code, so you know it will match the implementation. (Assuming all your automated tests are passing.)

The new features are all included automatically, so you can trust it’s accuracy.

Developers feel more freedom to innovate. They can experiment with different options and choose the best one without worrying about extra documentation effort.

Low effort

Good documentation is kept simple and is easy to do. Automation can help speed up some tasks.

You want it to be easy to review. If you use a source control tool like GitHub, the review process helps prevent wasted effort as it highlights any changes for you.

Documentation might not be optional if you are working on an application that needs a regulatory application. Automation can simplify this process by helping collate the vast amounts of information you need. It can also present it in a way that is more accessible to auditors.

Collaborative

The value of documentation is in sharing knowledge and sparking conversations. You might not document every discussion, but it helps to ask questions, share insights, and gain clarification. Good documentation makes collaboration even better.

If teams understand the features better, the software quality improves. They can access the info they need and see how it fits in the bigger picture.

Teams sharing responsibility for documentation gives benefits all round. Everyone can use it to share their learning and understanding to help others in future.

It can help new team members with onboarding. The info they need is right where they need it. They can learn about the project and how it works and find the necessary information.

Insightful

Easy access to relevant information encourages deeper thought and “joined-up thinking” when making decisions.

Clients often tell us how vital project insight is. Providing visibility of the status of your project to the team and stakeholders can enable them to make more informed decisions. It can also give them confidence in the status of the project. If a project is not going well, documentation can highlight this.

Visibility of test results or code quality metrics can empower teams to improve them.

Sounds great; how can I do it?

We have identified four steps to setting up Living Documentation for yourself:

1. Identify the data that is valuable to you

If it isn’t going to help anyone, leave it out.

Examples of useful data could be:

• Unit test titles and automated test run results
• Behaviour-Driven Development (BDD) tests and automated test run results
• Code quality results (such as code coverage, complexity scores, or habitability scores)
• Requirement documents
• Traceability matrices (showing the requirement and corresponding tests and results)
• Development plans
• Development processes
• Design decision documents
• How-to developer reference content
• Risk assessment results
• Glossaries
• Automated system diagrams (from code annotations)
• Export of current sprint work from tracking software APIs, such as Target Process or Jira
• Export of pull request comments from GitHub API (handy for regulatory)

2. Convert the existing data sources into a compatible format

Sometimes this might be placing original files in a repo alongside the code. Or you might want simple scripts to convert files and data into a compatible format or to access remote data (such as through an API).

We like to use Sphinx to build the living documentation. Sphinx processes RestructuredText (RST) format file markup language. We either write plain RST files or scripts which output RST format.

3. Run the living documentation tool and produce usable output format(s)

You can choose a range of output formats. PDF is good for reports you want to email, and you can use a subset of files to only include the most helpful information. A searchable website is accessible to most people and is auditor-friendly, this could be an entire site or a single-page of HTML. You could set up a dashboard-style overview page, or even just use plain text.

4. Put the output in an accessible location

Keep it somewhere people can easily access, such as a web server hosting a website or shared folder. Using a build server can automatically generate the documentation and push it to the required location when the code is updated.

Is living documentation the right fit?

Good living documentation saves time and effort and greatly improves project collaboration. If this sounds like something you might like to try, you can implement it in-house or reach out to our team at Bluefruit to help.

Written by Jane Orme.