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.

In my own opinion, my biggest weakness is asking questions. Often I didn’t know what to ask even when it was clear that I don’t understand anything. Still, you need to start somewhere…

In the world of autistic people, I found the book The Essential 5. This book says that autistic children have it easier, if you always answer 5 questions: “why?”, “who?”, “where?”, “when?” and “how?”. I have started to use those same questions to find out everything necessary in IT-projects.

Why?

If you don’t know answer to “why?”, there is no point in going to next questions.

Why is this project started? What goals does this project need to reach? What KPIs need to be improved with this? Why are these KPIs important?

Simon Sinek has written a book “Start with why”. I agree with the title without reading the book itself. This is the most important question, the easiest to ask – and most underutilized. From “why?” you can set priorities and lead to more suitable functionality. IT system is waste of everyone’s time and money, if it doesn’t correspond to that question.

“Why?” gives the goal to the whole project and puts it in the context of the surrounding world. This is the clear basis for making decisions by all parties. The opposite question of “why not?” is also important. As an example, it is not necessary to implement already existing functionality or currently less important requirement. It limits the scope and helps make sure it is ready in time.

Answer to “Why?” often doesn’t is not documented. I have not found any good techniques to make sure it is always added there. “Why?” should be part of vision, RFQ or project contract. As this is compiled by customer, it doesn’t have a standard structure. During business analysis, different techniques are used to examine the background (SWOT, MOST, PESTLE, business plan etc), but the goal is only a small part of it. “5 Whys” technique helps discover the deeper reasons, but in my experience, it is used rarely and only in the beginning.

If “Why?” is missing then:

• Work is mechanical and error prone for all roles – developers, testers, implementers;
• Later, when system is repaired or improved, they may contradict the objectives;
• Nobody knows whether described functionality is actually needed or an analyst’s nice-to-have idea.

Agile software development methodology solves the problem by bringing customer and developer behind the same table. Still, in this case “Why?” is only in their memory. After a few iterations, it is difficult to remember why the solution was created the way it was. Something important for the customer may be lost in further developments, and will need to be restored.

“Why?” also needs to be asked as sub-question of all of the following questions:

• “Why they are interested in the project?”
• „Why exactly this way?“
• „Why at that time or with that regularity?“
• „Why there?“

Who?

Who orders the project? Who will be using the system? Who is interested in this system for some other reason?

“Who?” is often the starting point of project because, as they say – the one who pays, orders the music. Customer’s “why” is the most important for the project and it is customer, whose goals are primary from project’s standpoint. Analyst still needs to view solution from viewpoint of all parties. Stakeholder analysis is used to find all parties, and you can use different techniques to do that.

“Who?” says to the analyst, whom they need to talk to, or whose interests they need to find from other channels.

There are also common answers to this question. First, the customer and different roles who will be using the system. Analyst will be spending most of the time with them or considering from their point of view. Additionally, there are roles that tend to get overlooked:

• Legal requirements (if customer cannot bring these up);
• Competitor’s interest (that we want to contradict);
• Accountant/management reporting needs;
• and needs of technical system administrators.

The discovered needs are usually contradictory, but analyst needs to find suitable solution for the customer.

Where?

Where does future user currently do needed activities? What is customer’s and users’ vision about where they could do these in the future? Where is information needed by stakeholders?

“Where?” tells you first about the architecture of future solution. For example, what views are needed, how the data is stored, which systems are involved – and which are not.

On the other hand, “where?” talks about devices used by future users. Maybe the user is a technician, who uses a mobile phone with small screen while on the site? Maybe they didn’t have some devices before and it is needed to procure them within the project? Maybe it is required for all future users to use specific operation system? Maybe it is reasonable to continue using existing solutions – partially, for transition or as replacement of some development.

Different aspects of “where?” are described in (nonfunctional) requirements, architecture and deployment views. It is also mentioned on process diagrams, user stories and use cases.

When?

When does a process start? What is the order of different processes, what is the frequency? When does user need to see any information? When do the process results need to be ready?

“When?” helps to decide whether to automate a process or make it manually accessible. Often used processes and information may need to be made more easily accessible or highlighted. It may be necessary to optimize time-critical processes.

“When?” gives mostly information about what the solution can be like. This information is described in requirements, processes and use cases.

How?

How do future users currently do those activities? What is the customer’s and users’ vision for how to do that in the future? How would it be most convenient/efficient/correct way to reach to the result? How can we provide best solution to customer within given time and budget constraints?

“How?” question is dealt with during most project meetings and hours spent alone by analyst. It helps you understand all details that you can’t find with previous more generic questions. It is also used to understand how processes work in system to be built or around it.

When focusing on “How?” there is risk to forget “Why?”. For example, you create system exactly the same way as current process that is based on paper or Excel use. There is no added value from process optimization in such system.

“How?” is mostly described in process diagrams, use cases or user stories. In my experience, the best way is process diagrams with descriptive remarks, because these don’t need specialized IT knowledge to read. Depending on the project, it still might be better to create user stories or use cases instead.

Conclusion

Maybe you wonder, why there is no “what?” question in this list? It wasn’t there in given framework – and whether through luck or some other reason, it is not needed. Analyst is answering this question with their work. Some customers do give quite detailed vision about what the future should be. Still, even in this case, it must be analyzed whether it really is the best possible solution. Using the analyst’s experience and analysis process, usually the final solution will be somewhat different. Too detailed vision given by customer may even draw out analysis process and make it more complicated; especially if analyst forgets to ask “Why?” because of it.

Those questions are clearly not exhaustive. You can go into more details in everything, and based on project, you may need to ask some very specific questions. Still, this framework helps cover biggest areas during IT project analysis. They help me start the discussion, if it is difficult for some reason, and keep the most important thing in focus.

Why would you use this framework – or not? Do you have some simple frameworks that help in analysis process? Add them below as comments or in our Facebook or LinkedIn group!