How to make documentation useful and easy to maintain?
If you’ve ever opened a document in the middle of a project and thought, “This is useless and probably outdated” — or never found any document to give you overview of the solution in the first place —, you’re not alone. Many IT teams think that documentation takes too long to create, no one reads it, and it becomes obsolete almost instantly. They should ask more often: “How to make documentation useful and easy to maintain?”
That’s why I wrote the book Optimal documentation: useful, up to date and convenient
Early in my career, I was just as frustrated. I saw teams skip documentation entirely, or worse, create piles of outdated files no one trusted. As a business and IT systems analyst, I couldn’t ignore how much time and money was wasted because the right information wasn’t available when needed. On the other hand, I felt those struggles first-hand — it is not intuitive to make documentation relevant and up to date, and nobody was able to teach me how.
Over the years, I discovered through trial and error documentation best practices that helped me keep on top of it. I found ways how to make documentation useful and easy to maintain, and genuinely supports the team — and that’s the approach I share in this book.
Here are a few ideas from the book.
1. There are too many bad arguments and myths that take away our motivation to document
The article Debunking 6 Myths About Documentation is fully incorporated into the book, but I also expand upon just bad arguments for writing documentation:
× “You have to,” “the boss said so.”
× That’s how it’s always been done.
× That’s the analyst’s output.
× To fulfill contractual obligations.
I hear these arguments often. If you encounter such justifications in your work – just because it’s required or someone said so – it’s no wonder you might lack motivation to write documentation. In such cases, it’s worth asking “why?” and truly unpacking the reasoning for yourself. Otherwise, it might indeed feel justified to leave the documentation undone.
Chapter 1: Why people don’t want to document?
To write truly useful documentation, it is important to understand why we write it, to whom and what kind of documentation is actually helpful.
2. Documentation should help you yourself
Often, I attend a meeting with a client where they explain their ideas and needs and answer all my questions. It seems like everything is clear… But then, as I start writing things down into a coherent whole, I realize there are still missing details or gaps that need to be addressed.
The structured nature of documentation naturally helps to think through the entire solution and highlight what’s still missing
Chapter 2: Documentation is useful to you personally
Good documentation isn’t just for handovers or audits — it’s a thinking tool. It helps you spot missing information early, reduces repeated explanations, and makes it easier to make solid decisions.
3. Integrate updates into your workflow
One of the most common frustrations I hear is: “Documentation is always outdated.”
But it doesn’t have to be this way – and of course, up-to-date documentation is far more valuable. And yes, keeping documentation up to date is entirely possible! This simply requires updating it as needed. Naturally, this means assigning responsibility to someone who has both the persistence and the skills to maintain it.
I explain how I’ve addressed this in the part titled “Up to date,” where I describe how the updating process can be integrated into your regular work routine as a natural part of documentation.
Chapter 1: Why people don’t want to document?
I also share practical ways to do this in my article Always Up-to-Date Documentation is Possible — and the book goes into detail about this framework of documentation best practices.
4. You don’t need to document everything
Busy teams don’t have the luxury of writing novels. That’s why my documentation best practices focus on right-sizing it to the project’s needs — enough to give clarity, not so much that it becomes unmanageable.
One must make smart choices between these models. For example, even a map can have many different views – traffic schemes, electrical installation layouts, cadastral boundaries, mineral resource maps, etc. You don’t need to create all of them – unless you’re building a centralized geoinformation service – just a base map and views tailored to show the information needed by your target audience. /…/
On the other hand, continuing with the map analogy, we can also choose the appropriate level of detail – at what zoom level do we need to view the map in a given situation? /…/
When documenting IT systems, documentation is often created as views with varying levels of detail, where a higher-level view includes components that are expanded in more detailed lower-level views. This creates a hierarchy in which the lower levels contain significantly more views/documents than the higher levels – and that raises the idea of not documenting every solution in such depth to reduce maintenance overhead.
Chapter 6: Sufficient documentation
Considering the types of documentation and the abstraction level necessary helps you make smart choices about your documentation, which helps us manage our workload – do only what is actually necessary. In the book, I explain how to identify the right models and the correct level of detail.
Ready to make your documentation useful and easy to maintain for you?
If you’re a business analyst, systems analyst, project manager, product manager, product owner — or simply part of a busy IT team — you can stop treating documentation as a chore and start using it as a productivity tool.
In the book, I walk step-by-step through understanding the frustration, value of documentation, to practical principles on how to make it truly helpful, understandable and convenient. Although I mention standards and frameworks where appropriate, this book focuses on documentation best practices that can be applied anywhere. In addition to the theory, there are exercises under most chapters. These help you deepen the understanding and apply it to your own specific documentation and processes.
Learn the full approach in the book: Optimal documentation: useful, up to date and convenient,
available as both e-book and paperback, or if you want to walk it through with your whole team, a training-workshop is available on the topic.