Working with heavy documentation requirements


In a previous entry, we looked at how to work with minimum specifications. Unfortunately, in practice, this is not always possible.

Let’s suppose you have won a contract to build software to manage medical records. The software would be used by the government to collate records and process relevant statistics. How satisfied do you think the taxpayers’ representatives would be with some minimal documentation and criterion for “it works”?

While even in this cases unnecessarily long form documentation is still useless, I have come to accept it’s also part of the constraints you must live with in order to practice software development.

All is not lost, in this entry, we will be looking at how to build software when heavy documentation is a must-have.

Consider documentation as a story in the backlog

For teams still struggling to adopt a technical practice such as unit testing, the advise I give is simply put it in your backlog and then have an acceptance test for it. This practice will hopefully nudge the team to using it consistently.

In the same way, it helps to acknowledge that documentation is work, thus have it as an item in your backlog. Not only will you be tickled to remember it, it also makes the cost of writing the documentation clear to everyone.

Use continuous integration tools

One of the riskiest parts of your application is in its deployment. Thus the running jokes on the idiot who chose to deploy the update on Friday 5 pm have in effect committed the team to work the entire weekend. Organizations have evolved documentation to help derisk this activity as much as possible. This includes documentation on how to stage, set up environments and deploy the application.

Thankfully, a lot of this work can be automated away by using CI/CD tools. By carefully setting up your environment so that not only is it replicable but a bot can do it for you, then you eliminate the need for documentation related to it.

Even if you are not familiar with CI as a technical practice, I would still encourage you to consider adopting a Platform as a Service Tool such as the ones provided by Google Cloud or Heroku. It will cost you more but the savings in development time and headache will be worth it.

Insist on requirements as a point of discussion

Unless you are reading for leisure, any other kind of reading is hard work. Furthermore, most books out there are just not worth reading. Now, if authors whose primary work is to produce reading material are not doing a very good job of it, what about developers who don’t consider themselves authors?

It’s then better to remind yourself and the organization you work with the point of documentation is to enable discussion between the various stakeholders not necessarily to get a comprehensive view of the workings of this system.

This slight change in wording means whoever is writing the documentation writes it with a particular person in mind and keeps it short enough to support a discussion without getting bogged down in details.

Work to understand the goals of the documentation

Rather than viewing documentation as another drudgery you have to go through, try to inquire why the organization cares so much about having such heavy documentation.

Sometimes, it may be an auditor who insists on a certain quality level. In such situations, having a one on one discussion with them would help you understand what their goals and for your team to work on how to meet the goals in an agile manner.

Follow your own process

Scrum and agile in general works but just like any other process, if you don’t abide by its principles, the results may vary. Thus in your quest to reduce unnecessary documentation load, ensure you are delivering working software, talking with stakeholders, in general, being a good scrum team.

In this way, over time, you will be able to make the case just because your process is remarkably different, you are still able to achieve the goals of the organization.

How have you worked with heavy documentation requirements in the past? Talk to me in the comment section below or on my twitter @jchex



Published by


Software Project Manager