About documentation: if, why and how?

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!