Let's say you need to choose some technology for your project, or you already have problems with some technologies, so you want to replace them with others. If you do not maintain a decision log, you have a high risk of making bad decisions that are biased, based on authority, and take too long.

The typical problems for a project with no decision logs are that decisions take a long time, decisions are random and suboptimal, team are unhappy, and nobody can explain why we use one solution but not another, even with its tradeoffs.

The root cause here is a wrong decision-making process that is based on anything but facts and their analysis.

The correct decision-making process must start by defining the problem we need to solve, conducting thorough research on possible solutions, presenting facts with both positive and negative aspects of each solution, and then choosing the solution that is good enough to solve the claimed problem.

If your process does not resemble this and you simply make decisions on the fly during team calls because someone pushes hard, or if your team uses arguments such as "let's use X because Microsoft uses it too", "let's do X because everyone else does", or "I used it in my previous project and it worked well, so let's use it here too" then your decisions are likely suboptimal in the long term. To fix this problem, you may introduce a decision log.

Converse a solutions in writing

Don't make calls with your team to make decision if you no have consensus. You will just waste your time and time of your team, and then team will be forced to make sub optimal decision under pressure.

Technical discussions should be conducted in writing. This format is preferable because it is asynchronous, allowing everyone ample time to consider the problem, conduct research, and present their arguments effectively.

If someone in your team cannot articulate their position in a text-based discussion, this is not a reason to convene a team call. Such individuals may lack substantive arguments and may resort to social manipulation to push their solution. This poses a problem for the project, as decisions should be based on facts and thorough analysis.

Write your decisions

When making decisions for your project, log them in a place accessible to everyone on the team, such as GitHub issues or discussions, wiki pages, Notion, etc.

Include the following mandatory sections:

• Potential solutions list with pros and cons for each solution.
• Chosen solution and an explanation of why this option was selected over others.
• Any potential problems associated with the chosen solution, if applicable.

You may add more sections if you want, like involved people or links on related decisions that make current solution are consistent or something else that will be useful in future, to understand why this solution been accepted and what context we had.

Decision logs force one to declare information in writing and assist in analyzing information. When all information about a problem and possible solutions is placed in one document, you and your team can see all known facts and related information, ensuring that everyone has had equal opportunities to speak and present their arguments. Decision logs help to gather as much useful information as your team can provide.

Without a decision log, you may lose some important arguments and make the wrong decision. This can happen for many reasons, such as insufficient expertise in some areas, not documenting all arguments, hidden motivations, or personal bias. However, with a decision log, you have a better chance of finding criticism based on facts and selecting only the best solutions.

Analyze your decisions and consequences

Use decision log as pull request that must be reviewed before merge.

Before make a final decision, review the summary you formed. You may found the problems in your research process just by read the summary. If your summary have only 1-2 solution for general problem, or the arguments looks not as facts, but as opinions, it may mean that you need more research before make final decision.

If you have a decision log and find that the current solution is not effective, you can simply try an alternative solution from the list. However, keep in mind that information may become deprecated over time. In such cases, it's important to initiate new research to ensure you have the most up-to-date and relevant information.