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 AS-IS from TO-BE?

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:

• AS-IS and TO-BE are separate documents, where you can clearly see, which situation it describes;
• TO-BE description is colored in 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. Which situation does AS-IS documentation describe?

People often talk about out of date documentation, but the moment when it gets outdated may be different in each team. Documentation is most often used to describe TO-BE vision, but at what moment the vision becomes reality (AS-IS)? Is it when the developer has finished programming, when it has been tested, or not before it has been deployed to production environment?

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.

With a conscious approach, always up-to-date documentation is possible

Although the principles are universal, there is no single right answer that works for every team in every situation — each option has its pros and cons. I cover these in more detail in my book Optimal documentation: useful, up to date, and convenient and on the first day of my Business and Systems Analysis Course, which I run several times a year. There, I also provide more specific recommendations for how to find the solution that best fits 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!