Agile documentation issues

Traditionally our main documentation issue has often been too much documentation – and being done when we have the least information (at the start of the project).

Some agile set-ups have started to have the opposite issue – not enough documentation.

There are mainly two different ways this can become a problem:

  1. insufficient of long-term documentation
  2. using too simplistic tools or models

Insufficient long-term documentation

Many agile teams think a lot on what documentation they need to support the development work. And sometimes they are very successful in reducing waste. But sometimes they forget the documentation needs for the entire product lifecycle.

This is rarely a problem in a strong team that is fairly static (same members). And by strong meaning that they use practices like Collective Code Ownership and are communicating well etc.

But if the team is not so strong, for example have very high dependencies on key persons or are not communicating well, lack of product documentation can be an issue.

It can also be an issue when the team is not static, if you for some reason need to move people between different products or you have hand-overs between different teams (yes, hand-overs are in general bad – but sometimes they can not be avoided).

The advice is to explicitly discuss both short-term and long-term needs when deciding on way of working and which documents, models and tools to use. But when doing this we should of course still keep in mind how much useless documentation we have produced in the past – and not make the same mistakes again.

Using too simplistic tools or models

Sometimes we get so enchanted by all wonderful agile things that we stop thinking about other options. Let’s say for example you are developing functionality in a complex system that is complex, involves interactions with several other systems, have a lot of different flows and rules. You’re trying to break things down into User Stories because that is the way you have been accustomed to work. But after a while you realize that you are having the same conversations over and over again and you realize that you are losing the big picture of the flow. Then you do a traditional Use Case and all of a sudden it feels so much easier to grasp (been in exactly this situation).

Sometime the simples thing that could possibly work is not the most efficient and I believe that some of the stuff we have done traditionally have a lot merit in certain situations – and we should not throw all the things we’ve learned over that last decade out the window just because agile is so hyped.

Leave a Comment

Your email address will not be published. Required fields are marked *

Scroll to Top