{"id":2158,"date":"2025-02-25T14:33:47","date_gmt":"2025-02-25T11:33:47","guid":{"rendered":"https:\/\/itbac.eu\/always-up-to-date-documentation-is-possible\/"},"modified":"2025-08-05T17:55:46","modified_gmt":"2025-08-05T14:55:46","slug":"always-up-to-date-documentation-is-possible","status":"publish","type":"post","link":"https:\/\/itbac.eu\/en\/always-up-to-date-documentation-is-possible\/","title":{"rendered":"Always up-to-date documentation is possible"},"content":{"rendered":"\n
\"Outdated<\/figure>\n\n

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\u2019s not worth creating it at all (I also wrote about this earlier in the article Debunking 6 Myths About Documentation<\/a>). <\/p>\n\n

I say it is possible!<\/p>\n\n

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

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. <\/p>\n\n

Why is IT Documentation so often outdated?<\/h2>\n\n

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.<\/strong><\/p>\n\n

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. <\/p>\n\n

This leads to a situation where systematic and reliable documentation simply doesn\u2019t 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! <\/p>\n\n

How to achieve up-to-date documentation?<\/h2>\n\n

You can develop a suitable solution for any team by considering the following questions:<\/p>\n\n

1. How do you distinguish AS-IS from TO-BE?<\/h3>\n\n

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: <\/p>\n\n