Why is your documentation getting out of date?

I have frequently started working on products where there was little up-to-date documentation. You usually only notice it as you go. You might find that one part of the analysis does not describe the latest changes. As you find more and more inconsistencies, you will not be able to trust any of the documentation, even though some of it might still be ok. So why does this happen?

How does documentation become out of date and what can be done to prevent it?

How does documentation become out of date?

Time pressure
I have often heard the argument that not updating the analysis will help to gain time. I couldn't disagree more:

• Either you know what needs to be added/removed/changed. In this case there is no effort in adapting the analysis.
• Or either you don't know and you will not be able to provide the information that is needed to the development team. Resulting in either you doing more analysis work or the developer making assumptions. None of which will help you deliver faster.

If you really want to gain time, you need to make sure you're specifying just enough. Don't waste time on making the perfect analysis or on using every possible analysis technique available.

The same logic applies when you are using a template. Don't fill in every field in the template, just to be consistent. Only fill in the information providing the most added value. An example I've often seen are templates for the user interface description. Instead of just filling in what was relevant, every possible screen element had been described. By doing this, the important information will get lost within tons of pages.

People can't find the existing documentation
When you are working with a team of analysts and people come and go, it will become more important to have some structure.

People can't update an analysis they can't find or don't know exists.

How can we add structure?

• If you want people to find the analysis, you can have some guidelines. If all teams use a similar structure to organise their analyses, people will automatically know where to look.
• It can also help to have a list of the available analyses of your product along with the location and whether it is up-to-date or not.
• Make sure you make the distinction between project and product documentation. Analyses which are hidden in project documentation will be harder to find as well.

The team didn't agree on which documentation should be updated
It is not useful to keep all documentation up-to-date. Depending on the maturity of the product, it might for example not be relevant to update your mock ups. In stead you can just draw the modification on a print screen.

But different people and situations will lead to different opinions. Make sure you have this discussion within your team and agree upon a minimum set of deliverables that needs to be kept up-to-date. Agile development teams might include this set of deliverables in their Definition of Done (DoD).

The same information recurs in different parts of the analysis
When you describe the behaviour of a system you often find that the same thing is described in the use cases, the user interface description, business rules, etc. This implies that when this part of the behaviour is impacted, someone might find the description in the use case, adapt it and think he has correctly updated the analysis. I try to always describe everything once in the analysis. If needed, you can always refer to this in other parts of the analysis.

What can we do to prevent it?

• Don't try to gain time by not updating the analysis
• Do gain time by being efficient and specifying just enough
• Agree upon a minimum set of deliverables, what you will keep up-to-date and for how long
• Facilitate people to find the existing documentation
• Don't repeat the same thing in different parts of the analysis

This post is based on an entry from my personal blog. I hope you enjoyed it. Let me know what you think!

Like this Blog?

Then you’re in for a treat! Visit Sarah Denayer’s personal blog, which offers many more hours of excellent reading material!