All posts by Kristin Meriniit

About documentation: if, why and how?

Documenting is difficult. People vector created by pch.vector – www.freepik.com

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!

Business analysts’ morning – Business analyst at crossroads – can’t do it the old way and the new way is scary

Online tutorial. Picture: Designed by pikisuperstar / Freepik

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.

What is business analysis and why is it needed?

Problem, analysis, solution. Photo: pixabay.com

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