Debunking 6 Myths About Documentation in IT Projects

Get ready, because we are about to debunk the myths surrounding documentation in IT projects! While documentation is essential when building a house, it often gets neglected in the world of technology.

We have invited Kaja Trees to help us explain why documentation is not a burden but a valuable tool on our journey in the IT world. She is an experienced Business and Systems Analyst and has a training called “Optimal Documentation: Enough, Connected, and Up-to-Date” (read more about the course HERE).

1. No one reads documentation anyway

Kaja suggests forgetting about detailed documentation where every nuance is precisely written. Instead think about who needs this information and include only what is necessary.

In your documentation, you should definitely include agreements with clients, tasks, and responsibilities. They help the project manager keep the project moving forward and let the developer know what their area of responsibility is.

When a new team member joins, it’s also beneficial if they can get the necessary information from documentation rather than through oral communication. For example, when a technical team member joins, understanding frameworks, tools, and project workflow is critical.

2. Code is documentation

Kaja states that code is documentation as much as the world is a map!

Yes, code contains a lot of information, but for large systems, understanding it can be as challenging as finding your way from downtown Tallinn to Rome. Code is very detailed, and getting an overview from it can be difficult.

Moreover, code is not understandable to the client and does not describe agreements – if code is documentation, there can’t be any “bugs”! Every change would have to be paid for by the client because, according to this logic, everything in the code is always correct, even if the developer has misunderstood something.

Good documentation helps everyone understand what the software does and navigate the code.

3. Documentation takes too much time

Kaja advises not to spend excessive time on detailed documentation. Think about what information is actually needed and document only that. The time spent creating such documentation is an investment that pays off later, with interest, when it can be used for planning updates and changes.

4. Documentation is always outdated

Kaja explains that documentation doesn’t have to become outdated! In her projects, she has learned to keep it up to date.

The key here is to include updating documentation as part of the natural process at an appropriate point. Software should not be updated without updating the documentation!

5. No One Likes to Write Documentation

Kaja points out that she genuinely enjoys documenting, and in fact, there are many people who enjoy writing documentation.

Choose diverse people for your team and let each person focus on what they enjoy. This is also one of the reasons why it’s good to include an analyst or even multiple analysts in a slightly larger project. Everyone can deal with the part of the work they enjoy.

6. Agile approaches don’t include documentation

Kaja asserts that the Agile Software Development Manifesto created in 2001 stated, “We value … working software over comprehensive documentation!” Over the more than 20 years that followed, this has often been interpreted as “we don’t value documentation.”

It’s forgotten that in the same manifesto, it says: “While there is value in the items on the right, we value the items on the left more.” Of course, the most important thing is that the software works, but good documentation can be a valuable tool in achieving that.

Documentation is not an enemy but a companion that helps the team navigate the complexities of the IT world. Finding the right balance that fits your project and team is crucial.

At Kaja Trees’s training session “Optimal Documentation: Enough, Connected, and Up-to-Date,” you can learn how to naturally write and update documentation to maximize its benefits with minimal effort. This is an opportunity you shouldn’t miss! You can purchase tickets for the training session in English, taking place on November 6 and November 8, 2023, HERE.

First appeared in Geenius DigiPro (in Estonian).