Always up-to-date documentation is possible

In many IT teams, documentation is random, fragmented, and outdated. However, systematic and up-to-date documentation helps maintain consistency in IT development, solve problems efficiently, and enable new team members to onboard faster. I’ve often heard that in agile projects, it’s impossible to keep documentation up to date, and therefore, it’s not worth creating it at all (I also wrote about this earlier in the article Debunking 6 Myths About Documentation).

I say it is possible!

In almost every team I’ve joined, documentation has been fragmented, outdated, or entirely missing. I’ve seen systems where the same functionality was developed multiple times in different ways. I’ve had to reconstruct the intended system state based on team folklore. And, of course, I’ve had to plan development work based on incomplete documentation. It’s a recurring frustration!

To change this, I have experimented with various approaches. I have found principles that help create, manage, and update documentation as a natural part of the process, even in agile teams.

Why is IT Documentation so often outdated?

Documentation is often imagined as following the traditional waterfall model: first comes analysis, then system design, development, and testing. Once the system is deployed, the documentation is considered complete. However, in reality, modern IT development is not linear. It is flexible, parallel, and consists of small iterations. Even existing systems are constantly being modified. Documentation needs to be adapted for the agile process.

In agile teams, documentation usually exists only as task descriptions or when specifically requested. It often lacks updates reflecting changes made during development and is not structured into a systematic documentation set. In the maze of various Confluence pages, readers can easily lose track of what has actually been implemented, what is still planned, or what was merely a discarded idea.

This leads to a situation where systematic and reliable documentation simply doesn’t exist. When team members leave, all knowledge about how and why a solution was built in a certain way disappears with them. No wonder there is so much reluctance toward documentation!

How to achieve up-to-date documentation?

You can develop a suitable solution for any team by considering the following questions:

1. How do you distinguish between AS-IS and TO-BE documentation?

Anyone reading the documentation should clearly understand whether it describes an existing solution or one that is still being developed. To achieve this, a team needs to establish its own convention. I have seen various approaches to solving this issue, such as:

• Keeping up-to-date (AS-IS) and future (TO-BE) solutions in separate documents, clearly indicating which state each document describes;
• The section describing the future solution is highlighted with color within the AS-IS documentation.
• With each change, a new version of the document is created. Instead of tracking the latest document version, the focus is on which document corresponds to the solution currently deployed in the production environment.

All of these approaches can provide clarity, but none of them fit every situation. The worst scenario is when different practices are used within the same team—this easily leads to confusion!

2. What state should up-to-date documentation reflect?

There is a lot of talk about outdated documentation, but the point at which it becomes “outdated” can vary between teams. When creating documentation, it usually describes a vision of the future, but when does that vision become reality? Is it when the developer has completed the code, when it has been tested in a staging environment, or only when it has been deployed to production?

The answer may not be the same for every team. Only by establishing a clear agreement on this can you ensure that the entire team interprets the documentation in the same way.

3. How do you update documentation?

From the previous point, you determined when updates should occur. You can only ensure that documentation stays up to date if it is integrated into the regular workflow.

• The task must have a clear owner. In different teams, this responsibility can fall on various roles, from the product owner to the developer.
• The responsible person must receive a reminder to ensure updates are made. My recommendation is to set up a clear notification—whether as a separate task or a calendar reminder—so that updates are done on time and the work doesn’t pile up.

Once the previous steps are in place, updating documentation becomes a quick and simple task. For me, it also provides a sense of completion and satisfaction, knowing that a task has been properly finalized.

Always up-to-date documentation is possible with conscious approach

Although the principles are universal, there is no single solution that fits every team in every situation—each approach has its own pros and cons. I discuss these in more detail in my upcoming book, Optimal Documentation: Useful, Up-to-Date, and Convenient, as well as on the first day of my Business and Systems Analysis Course, which takes place several times a year. There, I also provide more specific recommendations on how to find the best solution for your team.

I can confidently say that when these principles are consciously considered and implemented within a team, documentation becomes a valuable tool that you can always trust. In my projects, this is exactly the case!