The main difference lies in analysis experience: those who are just aiming to become analysts; those who have already gained their first experiences; and those who, in theory, could already teach trainings themselves. Interestingly, each of them finds something new in the training – although that “something” is always a little different.

Career changer – moving into the IT field without coding

In every group, there is at least one person who joins the training with the goal of starting work as an analyst or product owner. Usually, they have previously worked as either a project manager or a tester – they have already collaborated with IT teams, but inside there is a doubt: “am I suited to be an analyst?”

On the other hand, there are also those who want to move from a specialist position in some business domain into the IT field, but actual programming seems too intimidating. Becoming an analyst or project manager appears to them as a more reasonable alternative.

For career changers, it is usually very interesting when, at the beginning of the training, we talk about the different roles that perform analysis in various types of organizations and what their responsibilities are. Discussions about how to interpret job postings to identify the right role sometimes even continue at the lunch table and during breaks.

During the training, they usually discover that the role of an analyst is not some kind of mysterious secret art. When discussing what an analyst actually does and what lies behind those different job titles, a career changer often realizes that they have already done many of those activities. It has simply been called by a different name.

When those puzzle pieces fall into place and some gaps in knowledge are filled, it becomes easier to highlight relevant experience in a CV using terms that a future employer will understand. For me, the most moving moments have been when a career changer later sends me a message saying they have actually been hired as an analyst!

Beginner analyst – I do know, but I don’t really know how

The challenges of a beginner analyst are different. They usually have a university diploma in hand or a couple of years of experience, but still dozens of questions circle in their head: “How do I make time estimates for analysis? How do I find the time to create all the documents we learned about at university? I did everything the way I was supposed to – why did this project run over schedule?” They do have knowledge, but lack experience – they don’t know how to make the right choices among all those dozens of possibilities.

In the training, they do know how to create documents correctly, but the aha! moment is understanding in what order and in which situations to use a particular tool at all. They begin to better understand other roles and processes around them; they learn to make choices and to ask the right questions. Already during the training, I have often received feedback such as: “At work we just found out that the project scope needs to be reduced. I pulled out our slides and we found a solution! “

In summary, a beginner analyst gains clarity from the training: all those pieces – processes, people, documents, tools – form a single system. They start using the right tools at the right time, which makes projects run more smoothly and clients happier.

Experienced analyst – different techniques and experiences

And then there are the veterans. They have been working as analysts for years, have developed their own routines, and drawing a process diagram or a data model is like a second native language to them. They are in the minority in my trainings, and they mainly attend because there is training money available in some budget and there are few trainings specifically for experienced IT analysts.

At first, analysts with long experience may even doubt whether they can get anything out of the training at all, but soon I receive intriguing questions from them such as: “Does anyone actually use this method?” or “Why should it be done this way, we’ve always done it differently?” They often discover that they have been stuck with one type of project and that there are many more useful techniques in the world – new ones are being created all the time! For me as a trainer, the detailed questions about specific situations are also fascinating, as they provide engaging context for the other participants as well.

In their feedback, experienced analysts usually say that they especially enjoyed learning how work is done in different types of projects, and they are satisfied that they had the chance to try out different techniques. Some even admit that they discovered a gap in their knowledge or picked up a useful tip on how to do their daily work better. Not a bad outcome, considering they came with “just” training money and still found something practical!

What can be taken away from these stories?

When looking at these three typical participants, a pattern emerges quite clearly:

• The career changer gains the confidence that “analyst” is not such a complicated job, but rather the application of common skills in a new way.
• The beginner analyst finds structure – how different tools help and when to use them.
• The experienced analyst gains fresh perspectives and a few new tools for their toolbox.

In summary, this means that regardless of their background, everyone goes home with some important realization: “Aha, now I understand why this all really matters!”

And maybe that is the most important lesson – the work of an analyst does not only mean producing documents or drawing processes. It means understanding how people, technology, and business fit together. And when that understanding emerges, daily work also becomes much smoother.

Come and try yourself!

If you are reading this and recognize yourself in one of these types, then you are exactly the person this course was created for.

The next public training will take place from September 29 to October 3 in Tartu (with an online option available).
See detailed information and register here (training is in Estonian):

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!

“There are no analysts in our projects!” and “I don’t want to see another analyst in my projects!” are increasingly common phrases in IT projects. Yet, before the triumph of agile development, analysts played a critical role in preparing for IT development. So, how is it done now?

The topic is elaborated by Kaja Trees, a systems and business analyst with over 20 years of experience, who also shares her knowledge through training sessions. She has provided consultancy services in various companies.

The Analyst’s Place in IT Teams

According to Kaja, the structure of IT teams and the analyst’s place in them can be roughly divided into four groups:

1. Teams without analysts

Here, every developer does the analysis for their development task. This can lead to unevenly thought-out solutions, or a ‘hunchback’ system. Such systems may contain duplications, technological debt, and scaling issues. Users are often dissatisfied with the UX, and IT architects with the technical structure.

The challenge is maintaining the big picture, often done by a collective ‘hivemind’ rather than a central role. There are software developers who can collectively maintain the big picture and engage in necessary discussions with the client, though many prefer focusing on the technical side. Agile methodologies offer many practices to mitigate this risk. However, Kaja’s experience shows the need to be aware of the analysis role to avoid problems.

2. Teams with an analyst under a different title

The Product Owner, IT Architect, or even Scrum Master might fulfill this role if they have the relevant skills. This is like doing “secret” analysis to bypass strict restrictions.

The risk here is that their other activities may not receive enough attention, though they are also important. If there is a good balance between developers and other roles, such a team can function very well.

3. Teams Where the Client Conducts the Analysis

This means the client has a strong business analyst who maintains scope and logical coherence of the solution, preparing development tasks (like user stories) and ensuring that the solution is optimal from the client and user perspectives. Ideally, they have an IT background to utilize IT capabilities without overcomplicating things. The development team receives a task that is understandable to developers, allowing them to focus on the technical side.

The biggest risk is when the analyst does not fully understand how IT systems work. Here, an open dialogue with IT architects or developers, who think along and suggest alternatives to proposed solutions, is helpful.

On the other hand, such a team must have either an IT architect or excellent developer collaboration to ensure that all parts of the solution work as a unified whole from a technical perspective. Without a grand vision, for example, development might start on a platform with insufficient scalability for the final solution.

4. Teams with an analyst as part of the development team

The analyst’s task is to prepare tickets just as a developer’s task is to develop them and a tester’s is to test them.

If the client lacks a strong, technologically savvy business analyst, then the project team must fulfill this role. Kaja has been in this position in many projects and found it can work very well. However, purists of agile development see this as sacrilege, believing that the development ticket should be solely in one person’s hands from start to finish.

Analysis is of critical importance

It’s vital to understand that analysis is a critically important part of any project, no matter who does it. To avoid disputes, Kaja often approaches the responsibility of analysis by looking beyond job titles and defined roles – finding the person who takes on this responsibility. An analyst, in her view, is someone who does the analysis, regardless of their job title or where they “sit” in the team structure. The notion that only people with the official title of “analyst” can do this work is limiting and creates conflicts.

Similarly, Kaja’s taught “Business and Systems Analysis Course” is intended for all roles involved in business or systems analysis – including developers, product owners, Scrum Masters, testers, and project managers. It teaches analysis skills through thoughtful theory and feedback-based practice and is an investment in personal and company development.

The article was first published in DigiPRO (in Estonian).

In today’s business landscape, IT projects have become a crucial part of innovation. However, these projects may not always deliver the expected results and can even go very wrong. Kaja Trees, a business and systems analyst with decades of experience in diverse projects, has put together a course titled “Navigating the IT Landscape: A Business Professional’s Guide to IT Procurement and Successful Collaboration.” Here, she reveals common obstacles in IT projects and offers practical strategies to overcome them.

1. Exceeding Budget and Deadline

Problem: IT projects often tend to exceed budgets and timelines. Given that IT projects are not cheap and business outcomes depend on deadlines, this poses a significant problem for businesses.

Solution: Clear communication is the key to successful budget and deadline management. Pay special attention to ensuring a shared understanding in the following areas:

• Define clear project goals and ensure everyone understands them uniformly. It’s crucial to highlight priorities – which goal is more important than others.
• Ensure that the project scope is clear, and any changes are based solely on the project goals. If necessary, abandon less critical project outcomes to achieve more important ones.
• When selecting technologies, ensure that all options, along with sufficient explanations and pros/cons, are presented. The client must understand how to make the best choice based on project goals.
• Use an appropriate project management technique for the project and ensure that decisions are made by the client.
• Regularly evaluate what is working well or not and adjust accordingly.

Exceeding budget and deadline can be acceptable if the result is a product that is worth it. However, these decisions must be made consciously. Ignoring the above can result in no outcome at all – all the work and money have gone to waste.

2. Unusable Results

Problem: Even impeccably executed projects can fail if end users find the system unsuitable, forcing them back to traditional, less efficient methods.

Solution: The system can conflict with end user demands in several ways. Solutions include:

• Functionality must meet users’ needs and qualifications – involve business and systems analysts to ensure the system aligns with user needs.
• System usage should be simple; information and buttons where needed – involve user experience (UX) specialists to ensure an intuitive user interface.
• The system must be fast enough – involve system architects to ensure technological choices meet expected usage intensity.
• The system must deliver what is expected – involve quality assurance engineers (testers) in your team.
• Go straight to the source – involving actual users in the team through user interviews or user testing provides the best insights into what real users need.

Every IT project is teamwork, with each member playing a role. While some individuals may need to fulfill multiple roles, if any aspect is left uncovered, the project may be completed, the system built, but it won’t bring the desired benefits.

The IT world has evolved differently from the traditional business world. It has its project management concepts, specific roles, innovative practices, not to mention technical terms. To successfully carry out IT projects, it’s worthwhile to be aware of the peculiarities of the IT world and consciously consider them.

By enrolling in the “Navigating the IT Landscape” course, you not only acquire essential skills but also gain confidence in successfully managing complex IT projects. In the course, Kaja shares real-world experiences and explains in detail everything a non-IT person needs to know for successful IT collaboration and avoiding the problems that plague many IT projects.

First appeared in Estonian in Geenius DigiPro here: https://digipro.geenius.ee/sisuturundus/mis-saab-it-projektides-valesti-minna-ja-kuidas-seda-valtida/

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).

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!

On 26th of November 2020 I attended a “Business analysts’ morning”, a web seminar held by Nortal The topic was, “Business analyst at crossroads – can’t do it the old way and the new way is scary”. The first speaker was the president of ITL and partner of Nortal Andre Krull who gave a general overview of what is going on in the IT market. After that there was a panel where business analyst experiences were shared by Kadri Siinmaa (UX and innovation consultant, adventurer), Inge Prangel (Nortal AS, senior business analyst), Meelis Lang (Helmes AS, development manager) and Antti Haljak (business analyst and designer, freelancer).

Interesting thoughts

In summary, it was very good to hear about the experiences and approaches of different people. Some things that were said stood out for me and so I want to bring them out here. Most of the points are positive, but I do also have a few small complaints. Let’s start with the positives.

When panelists were asked, “what is the most difficult thing in their work?” it was interesting to hear that nobody complained about the lack of technical skills. The main issue was that communication between people can be quite difficult. It can be that the teammates are very different people and want different things, or you somehow have to say to the client that what they want is not what they need. We wrote about communication skills in our article What skills are needed to be a good analyst? and listening to other business analyst’s experiences it is confirmed again and again that those are indeed very important skills.

It was also emphasized that self improvement is very important. You constantly have to analyse your work and yourself. What went well, what not so well and how to do better. There were no specific examples, but they said that they will update the event page with book recommendations, I am waiting with interest. The book I am most interested in is the one that was mentioned during the webinar and is about receiving feedback.

Panelists themselves said that they mostly do self study, when they find a topic that they don’t know much about then they will investigate it and learn more. Another thing that they do is that they listen to podcasts (or read articles) about a wide array of different things and if they hear something that interests them more, then they will find out more about that topic. One general overview podcast that was mentioned was Making Sense with Sam Harris, it has been in my podcast backlog for a while now so maybe now is a good time to finally listen to it.

Business Analyst certificates were also mentioned. Inge Prangel is an IIBA (International Institute of Business Analysis) certified analyst and she was asked by a listener if this has been useful. Overall consensus was that if you are mostly working on Estonian projects then it does not matter. However, if you want to take part in international projects then this certification might be asked for. The exam itself is based on IIBA provided materials so unless you use them in your work a lot, there is not much merit in the learning process either.

Final positive thing that I want to mention is when a question was asked about how a person would get to be a business analyst. Of course books and courses were mentioned, but the main answer was to go find a business analyst through your friends then invite them out for coffee (bonus points if the business analyst doesn’t have to pay) and ask about their experiences and overall advice. In short, find a mentor, either inside your company or outside. The panelists offered that they can be contacted like that and I would add that you can also contact me (Kristin) or Kaja. We don’t drink coffee, but we will happily have a chat over a cup of tea.

What I would have liked to hear about more

Now we get to the complaints part. When a question was asked about what is the most important thing about business analyst work, the answer was face to face meetings and how the projects don’t really get going without them.

I am going to disagree here. Obviously meeting face to face is a very important communication tool but there are situations where it is not possible. Especially now with COVID-19, it is recommended to not meet up with people. Since the title of the webinar was, we can’t do things the old way any more, then I would have especially liked to hear how face to face meetings have been very important until now, but since we can’t do them as much at the moment, this is how we cope. No matter the situation, projects still have to proceed, be it either with mandatory cameras or allotted time in the meeting for general chat.

These last two things I mentioned are the things that I have been using quite a lot lately. In the last year I have mostly taken part in projects where some people sit half a world away or just stay in their home offices due to COVID-19. Despite that, I still have had to find ways to get people communicating and the project moving. Of course it all depends on the people, and whilst I have been pretty lucky with my team members, I  recommend looking up articles or courses that give tips on how to manage virtual teams effectively and what kind of tricks can be used.

My final complaint is that there wasn’t too much mention about what this “new way” is. When I looked at the title, I wondered what it would include. Will they talk about how agile processes have changed the way business analysts work? Or, will they talk about how their work has changed due to issues caused by COVID-19? Unfortunately neither was mentioned.

Overall it was a very nice event and thank you very much to the organizers and participants! I am already waiting for the next webinar, or depending on the situation, face to face meeting.

* Disclaimer – All the concepts in this article are written from an Estonian point of view. Some words have different official definitions in English (like Business Analyst, Business Consultant etc.) but in this article they and their meaning have been translated from Estonian.

In Estonian there is only one word for business analysis, “Ärianalüüs” and it is used for both business analysis and business intelligence. This can create a bit of confusion when talking about business analysis in Estonian, because quite a lot of people think you are talking about business intelligence. However, there is a difference between these two. Basically, the goal of business analysis is to map and describe processes and business needs. On the other hand, the goal of business intelligence is to find the numbers that are important for a business and to analyze these numbers. In this article and overall in this blog we will specifically be referring to business analysis.

The confusion between analysis and analytics is one of the reasons why I wanted to write about this topic. The other reason is that during my career, I have not had much chance to see proper business analysis. Something has been done for quite a lot of the cases, but without the understanding of what should have been analysed, in most cases the result is the description of the software system that is wanted. Business analysis however does not mean that the end result has to be software, quite the opposite. It might be concluded that the processes themselves should be changed and no additional IT systems are needed.

What is business analysis?

So, what exactly is business analysis? There is a short description of it in ITBAC blog What is IT and Business Analysis?, but to summarize, business analysis is discovering and mapping the needs for changes in the organization. The article also mentioned that there can be two different roles responsible for it, namely Business Consultant and Business Analyst. A Business Consultant will be mapping the general needs and a Business Analyst will look into the detailed processes connected to each need. Both roles are doing business analysis but on different levels. Business Consultants look at things from an overall point of view while Business Analysts go more into detail.

We will not go into too much detail about what Business Consultants do. In general they sit down with the stakeholders and help put together the overall vision and goals for the company. They describe the internal and external influences, pain points and risk factors. As a result goals and KPIs (Key Performance Indicators) can be decided on, which in turn might be the catalyst for change.

ITBAC focuses mainly on the Business Analyst role and it’s activities. Business Analysts are called in when the need for change has been determined. Their job consists of looking into the connected process and how change should be realized. For example, needs for change can be following:

• Our online store has very low sales, we need to find ways to raise the sales numbers.
• Clients are not happy that our feedback process is slow and they are going to competitors. We need to find ways to improve the process.
• Laws changed and our company is not compliant with them. We need to go over the processes and software systems and describe the places that need changing.

Business Analysts take the problem description, start to investigate it methodically and after documenting the results they can also offer different ways to solve the issue.

There is no definitive process for doing business analysis, in some cases it is necessary to do things that are not needed for other cases. But there are some general things that are necessary most of the time:

• Stakeholder mapping (internal, external etc.)
• Description of the current situation (process diagrams, requirements etc.)
• Proposed solution and expected results (process diagrams, requirements etc.)
• Solution value estimation

It is important to mention that the proposed solution can not be a description of a software system. The result of Business Analysts’ work can be that an online store is needed and that it must be possible to put the products into a virtual shopping cart, but there should be no more details about the software itself. For example the following text is not a very good business analysis result: 

“After opening the online store, the user should see the list of products with pictures. After clicking on the picture product page is shown. On the product page it is possible to click on the shopping cart icon to add the product to the shopping cart.”

Why is that description bad, if we leave out the wording and how superficial it is? Because the person who wrote it does not have a lot of knowledge about the technical side of online stores nor best design options. This might be how they are used to shopping online and so that is what they describe. There might be lots of better options available, for example most of the stores have the option to add products into the shopping cart in the product list, without the need of an additional page and click.

To summarize, Business Analysts start their activities when the need for change has been identified and they will describe the stakeholders, processes and whatever other things that are necessary for that specific situation. When the current situation has been described in enough detail, then it is possible to decide on what the requirements for the new solution are, how it should work, and what is the expected value for the company. With this information it is possible for the IT Business Analyst to start designing the needed software, if it is necessary of course.

Why is business analysis needed?

Why is business analysis needed? A simple way to find the answer is to ask yourself, do you want to use or be involved in a software system development process where the stakeholders are not known and the requirements have not been described or decided on? If business analysis has not been done beforehand (at least to reasonable extent, I am not talking about the long business analysis process as described in Waterfall methodology) then the most common result is that during the development process new stakeholders and requirements are found and the scope, duration and cost of the project will change. In the worst case the project will be cancelled and there is no result at all after a sizable expenditure of money and time.

Another important reason for business analysis is to find how much value will be provided as the result of the change. Will it affect the internal processes and save money and time for the company? Will it raise the customer satisfaction and sales? If those things are not known then it is possible that money and time will be used on an unnecessary solution, and after completion it will not be used. The reasons for not using the software might be different, but doing business analysis and evaluating the value of the change will help to avoid quite a few of them.

Life has shown that during the development process, new things are always discovered, no matter how well you prepare beforehand. What is important is, how many of those unexpected things will you find? No matter what methodology is used, all the new things that need to be added will cost time, money or other functionalities. If business analysis is done before the development, then it will lessen the amount of changes that need to be done during development, and as such will save money and time. Overall, it will result in a better, more comprehensive solution.

Previously, I wrote about which character traits are needed for a good analyst. Just having the correct character however is not enough – you also need some skills. In this article, I will not be able to list absolutely all skills that a good analyst needs. Instead, I will list here three most important groups of skills.

Office worker basic skills

These are basic skills that are needed by all office workers and are useful also elsewhere. Unfortunately, these skills are not mostly taught in schools. However, missing these skills has a painful outcome – it will be more complicated to collaborate and keep a pleasant relationship with the customer.

Office worker basic skills are:

• Politeness – polite behavior, suitable dressing, using appropriate level of formality for the environment, proper document formatting.
• Relationship-building – small-talk, keeping appropriate parties informed, expectations management, keeping promises.
• Self-management – time management, prioritization, own tasks management.
• Using office software – using programs for e-mails, documents, spreadsheets, online meetings.
• Leading meetings – be it interviews, workshops, negotiations, or presentations. Analyst needs to be able to lead meetings face-to-face, by video bridge or even in written form.

These skills may seem very basic and obvious. Unfortunately, I have often seen that these skills are lacking either for myself or my colleagues. In real life, some of these may be forgotten during activity if you don’t put knowing focus on them. These are skills that always need additional practice.

Communication skills

Analyst may be described as mediator between different roles in the project:

• different customer representatives to discuss business requirements with;
• developers and architects, who need technical description;
• project manager, account manager etc, who need updates on project progress.

Analyst must be able to translate between these different roles. They must choose appropriate terms, point of view, level of detail and subjects for the audience.

In addition to roles, analyst must also consider personality types. They must manage also the more extreme forms of communication, for example:

• shy people, who don’t stand up for their requirements;
• chatty people, who tend to take the discussion off-topic;
• visual, written and auditory communication types, etc.

Analyst may encounter some complicated situations in their work, for example:

• Contract or change negotiations;
• Scope reduction negotiations;
• Communication with participants that are uninterested or object to project implementation;
• Resolving conflicting requirements;
• Finding solutions under big scope, stress, and nearing deadlines
• Etc.

Although analyst is not the main responsible in all these situations, they must support their project manager and escalate as needed. They must have the ability to manage tensions in all situations and keep the discussion on planned topic. They must be ready to lead the conversation, explain different facets of the project, etc. Here, the most useful skills are active listening, assertiveness, negotiation skills, presentation skills, etc.

Many analysts don’t acknowledge that communication skills can be learned or that they should be studied. Unfortunately, professional and effective communication is not natural – it needs conscious practice.

Analyst’s technical skills

Analyst’s technical skills are specific to analysts and they are obtained by studying the profession.

I consider main analyst’s technical skills to be primarily different documentation skills:

• Taking meeting notes;
• Visualization options, including diagram markup languages – ex UML, BPMN etc;
• Knowing documentation types – ex use cases, user stories, form or integration specifications etc.

In addition, I consider here knowledge about the following:

• The way IT-systems work (IT analyst needs more in-depth knowledge here than business analyst);
• Common analysis frameworks and using their patterns;
• Ability to read and use standards;
• Development methodologies and analysis techniques;
• And many more.

With experience, analyst gains ability to choose appropriate framework, standard or methodology for each situation.

Analyst’s technical skills are most easily learned and they are the biggest focus when hiring analysts. Still, many analysts’ skills are one-sided and need additional study.

Analyst training options

There is no systematic training regimen for analysts after university completion. You can find online courses from internet, but you need to know what to search for.

There are many books and courses about office worker basic skills. The quality is uneven, but it is possible to find truly beneficial courses both locally and online. It is essential to participate in these as practical trainings to practice the required skills as role play.

Analyst technical skills can be studied at TalTech Business ICT (in Estonian)  on both bachelor and master level and in Computer and Systems Engineering (in English) master level. In universities’ general IT programs, these skills are only taught in high level. On the other hand, there are countless books on these topics. Still, learning from a book might not be applicable on local market.

In addition, I have found in discussions that HR has lack of systematic mapping of analysts training needs. I hope this article gave a summary of the skills that are needed for an analyst in my opinion. Add your own opinion here, in our Facebook or LinkedIn group!