The importance of having a decision documented
How many times do you start to discuss a solution to a certain problem with your team, and one month later or more, you realize that you don’t remember why you took that decision?
Yes … I know the answer … a lot of times or always … except if you have the memory of an elephant ?? But it’s not my case.
This happens a lot of times in a lot of companies.
In this article, I’ll try to explain how we can elaborate a decision document and what kind of information is useful to include. If you use your best friend .. Google … to search the Decision Log term, you will find a lot of information about it. In my company, we use the term Decision Log for these kinds of documents, but in this article, I will use the name Decision Document 🙂
To understand what we need to put in a Decision Document, let’s start with the questions:
- What is a decision?
- Why do we need a decision?
When someone presents you with a problem, either a business or a technological problem, what do you do? You start the discussion with your colleagues and they find a lot of options to solve the same issue. At the end of the discussion, you make a decision. Sometimes you aren’t sure about the option that you prefer and the team starts voting on the options to find a decision.
Usually, this is what you do in an informal way: just talking and drawing on a whiteboard.
This should give you some ideas for what topics to include in a Decision Document. Here they are:
- 1 — The problem
- 2 — The impact of this problem
- 3 — The options that you have
- 4 — Your/Team’s recommendation
- 5 — Relevant Stakeholders that need to contribute to this decision
1 — The problem and/or some background
Here is where you will explain in detail what your issue is. You can also put here how someone can reproduce the problem or some examples of the problem.
Sometimes it is not easy to reproduce the problem but I am sure that you can use some examples that make your explanation clear.
2 — The impact of this problem
When you have a problem that you want to solve, certainly there is an impact from it. That’s why you or someone else wants to solve it. So please, try to identify the impact. Even better if you can help quantify the impact by backing up your description with numbers.
3 — Options that you have
After you analyze the problem, you can start thinking about different solutions for the problem. When we have a lot of people reviewing the problem, they can also find some solutions/options and they can contribute their opinions.
For each option, it is very important to have several kinds of information:
- The explanation of the option;
You can also add a diagram to help your explanation, if applicable ( it is useful for software development problems )
- The advantages of this option;
- The disadvantages of this option;
- Technical debt added or removed
- Major work blocks that you need to do
- Estimated weeks to implement
- Risks that you can have
- Scalability concerns or other
- Estimated costs in case the solution requires a new third-party service or piece of software.
4 — Your/Team’s recommendations
Imagine that the owner of the document was the person that wrote all the options above. When this happens, it’s important to put your recommendation here and explain why.
5 — Relevant Stakeholders that need to contribute to this decision
It’s really important to identify who are the right people that need to see the decision document and contribute to find the right solution — and/or to know about this issue and understand what the team will do. A good list of stakeholders will be familiar with some aspects of the problem and can provide different perspectives of the impacts of each option.
Future viewers of the Decision Document will also know who handled and contributed to it.
Once we have all the documents ready and details on our options for this problem, it’s time for each contributor to vote on an option. Ideally you should try to have a consensus on what can be the right solution for that moment.
Often a consensus is not possible because all the options have tradeoffs that might be more or less important to different stakeholders and their perspectives. When this happens pay attention to the advantages/disadvantages of each one. Frequently stakeholders may have to agree to disagree knowing that a decision must be made and there might not be a perfect solution for everyone. It’s important to identify the chosen option and also explain why you recommend it. This process also helps ensure that the other perspectives are at least acknowledged and considered.
Final words
Now you are thinking, why do we need to do all of this? Can we just make a call to talk and decide a solution to the problem?
The answer is of course, but it’s essential to have a meeting note after that. Do you write meeting notes after all your meetings? Hmm … I have some doubts about that. The goal here is to have a document with all the discussion in a writing mode because you can recall one year later why you took that decision, what happened etc… But of course, for quick decisions, you can make a quick call, and that’s it 🙂 Another important thing to point out here is that today’s decision can change after because both we and the software continuously evolve.
Thank you for your attention, please feel free to comment and share your thoughts, opinions, and experiences.
