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 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!

Part of Business Analysts’ work is documentation, requirements need to be written down, processes need to be described and all kinds of other information needs to be gathered and preserved. All of this is not easy. Documentation can be used in many different ways, so it’s important to think through who will be reading it, how detailed the information has to be and what is the best format. Generally it can be said that documentation has to fulfill the following conditions: It has to provide necessary information, it has to be changeable and the effort put into it has to be reasonable (documentation supports software development and is not a goal on it’s own).

Due to all that, once in a while I spend some time thinking through if I write as good of a documents as I can. Do I write too much or too little? How can my documents be more informative? Can I improve the structure? What kind of different formats can I use?

Unfortunately, every project has different documentation needs and so I can’t describe the one and only way of documenting (I haven’t found that myself). What I can do is give some pointers about what questions you should ask from yourself before writing the documentation and hopefully answers to those questions will help with understanding what you should be writing.

Before getting to those questions I want to go over the general ones of “Do we need to document?” and “Why do we need to document?”. 

In the Agile Manifesto one of the values is “Working software over comprehensive documentation”. This has had an unfortunate result where one of the more extreme views born out of it is that there is no need for documentation at all. My personal view is that documentation is definitely needed and further on I will answer the question as to why I think that. Overall I support documenting using the agile principles, which means, document as much as you need when you need it. But definitely document.

Another view is that code is documentation. Yes, there are projects where well commented code is enough and there is no need for additional documentation. Those projects however are quite rare. If the code is not commented then it has no value as documentation. The reason is that programmers make errors when coding and if the purpose of the code is not written down as a comment then in the future it is impossible to know if things are working as intended or not. Besides that, code comments are a very limited format of documentation for many reasons. It is difficult to visualize things in text and stakeholders or even some people in the project team do not have the skills nor the means to read it. 

Why do we need to document?

1. People forget – The lifecycle of software can vary but in most cases it is usually more than one year. Potentially even a lot more. During that time there will be questions about the software, for example “Did we develop that functionality?”, “Is this functionality working as we planned?”, “What does this functionality do?” and a lot more. The further away we get from the end of development, the more likely it is that people who made the software will not remember the answers to those questions. If this information has not been documented then it is now lost and it’s not possible to answer those questions. Best case is, it will have no effect but it is more likely that the result of not answering those questions is loss of time and money. Things that were not in original scope, will be claimed to have been or duplicate functionality will be developed.

2. People change in the project – People get sick, go on vacations and change jobs. This is normal and it should not mean that the information they have is either temporarily, or in worst cases forever, unavailable. To make it easier for other people to take over and continue the work, information needs to be preserved one way or another. The perfect case is when new people can be mentored, but this might not always be possible and in any case, mentoring also needs supporting documentation.

3. To confirm common understanding – When somebody orders software with specific demands then the documentation is used to confirm what functionality was ordered. Business analysts describe the functionality in documentation and after discussions with the client this document will be agreed. Later on it will be used as an official document for billing and issue solving.   

I am sure there are more reasons to document but the three that I mention are the most common ones in my work.

In addition, I will also add a few examples that are not very good reasons for documentation.

1. Because the client wants documentation – Yes, there are contracts where the needed documents have been specified beforehand. As a Business analyst it is our job to find out the “Why?” of those documents. Why those specific documents are wanted. We need to understand what the client needs from those documents and what they will be used for later on.

2. We need input for developers – Yes, it is helpful for developers if there is some documentation for the functionality they are developing. However, input to developers should not be in written format, alone. Developers will want to understand exactly what is it that they will be doing and this does not come across very well in written format. Documentation should support verbal discussions with the programmer, and during those discussions developers will get a good idea of the required functionality as well as offer solutions. 

What do we need to document?

Now that we have gone through the reasons why to document we get to the more difficult part of how to actually write it all down. As mentioned before, there is no one way of documenting. Each project has its own needs. Some projects need integration documentation, some can make do with only user stories and others need something completely different.

To better understand, what kind of documents are needed, there are some general things that should be considered:

Why is the document needed?

Again with the why. Before we went over why documentation in general is needed, now we need to think about each document separately and why this specific document is needed. What is its purpose? Why are we writing it? When the document is done, how will it be used? If the receiver of the document says that they will not be using that document for anything then there is no point in wasting time on it.

Who will be reading the document?

It is necessary to know who will be reading the documents so it is possible to write down appropriate information. For example, some documents are created to pass along technical information. For those documents you will want to write down detailed information and only concentrate on a very specific subset of data. This document will be read by people with technical knowledge (architect, developer etc.) and business side representatives do not need to fully understand it. 

If a document is meant to be read by everybody, then it is not a good idea to put too many details into it. Rather it is necessary to concentrate on an overall view and leave details for other documents. Those kinds of documents are usually meant to be read by client side people or people with business knowledge from the developer team and they have to contain different information and in a different format than previously mentioned technical documentation. 

These are descriptions of two extremes of document readers. In reality there are more roles in a project and for each it is necessary to understand what they need out of the documentation.

Is it a long term or temporary document?

Not all documents need to have a long life. Some documents are needed only for as long as it takes to process the information contained in them. For example, in my experience, a prototype is only useful for as long as it takes to develop the user interface that it describes. After user interface development is finished discussions and changes will be done using the working software and the prototype will not be updated (after reading this Kaja said that her experiences with prototypes are different, but she does agree that some documentation is temporary). Prototype is only one example, there can be other documents that are only useful for a short time. Overall temporary documents tend to be the ones that are used to give developers detailed input for their work. After software has been realized, it is very difficult to keep the documentation updated with that much detail and usually there is no need for it.

Long term documentation is meant to keep more important information about the system and it will help to find answers to questions that might arise. It is up to the writer of the document how detailed the information is, but it definitely has to be kept up to date. If it is not kept up to date, then the document loses its meaning. Yes, that means that whenever there is a change in the software, the documentation also has to be updated (if the change affects information in the document). Due to that, long term documentation should be well structured, easily searchable and changeable.

How to write documentation?

As said before, writing documentation is not easy. First you need to understand what to write and then you need to figure out how to write it. Luckily for us, lots of different documentation formats and standards already exist.

When we think about overall guidelines then one of the main ones is that documents have  to be structured. In the future somebody will be going through the document to find information and structure is one of the ways to make finding specific information easier. Another general guideline is to visualize as much as you can, nobody has time to read though several pages of text (ironic thing to say in a blog article, isn’t it). Process diagrams, state diagrams, just boxes or circles, whatever else that helps with creating an easily understandable picture. For example, in my use cases I have started to replace the written body of the use case with a process diagram. It gives a better picture about alternative flows and overall picture.

For written documentation use cases and user stories are both good. Or you might also want to use some other form of structured text. The important part is that you will want to write down as many details as are needed at this specific time. Emphasis on the “As are needed” part. For example, the whole point of user stories is that they are short. They are not meant to contain all the details of the functionality, they are meant to be short summaries that will create discussion. After the team has discussed the user story, the important points from the discussion will be recorded as more detailed documentation. The discussion will help the team to understand what kind of input is needed for the developers. What information can be written down with few sentences and what will be written to the long term documentation and thus needs more work.

If you write very detailed documentation before discussions and development, then you need to be ready to spend a lot of time on changing it.

I am going to repeat once more that long term documentation has to be kept up to date or else it will lose its meaning. After bug fixes or small changes, the Project Manager, Product Owner or Business Analyst should go over the existing long term documentation and do the necessary changes. This has to be one part of the overall change process. One of the main reasons why people don’t think much of the documentation is because usually it is not up to date and it is not possible to find information that is needed. To avoid that, it is necessary to understand the importance of up to date documentation and make updating it part of the overall processes.

I did not go into any detail about different types of diagrams or models that can be used in documents. The reason is that there are quite a lot of different options and each of them has their good and bad sides. To know what the different options are, my own bookshelf contains Business Analysis Techniques: 99 essential tools for success and BABOK. Those books contain a lot of information concerning Business Analysts’ work and they also have examples about diagrams, models and other documentation. 
Despite its length, what I wrote here is still a very general overview about documentation. If you have any questions, you can always post them on our Facebook or write us an e-mail: kaja.trees@itbac.eu and kristin.meriniit@itbac.eu.

Feedback and questions make us happy!