While working on an IT project, thousands of decisions are made. One of the most important tools to handle the project, are decision logs. Most articles praising the benefits of decision logs focus on how they help to make, remember or fine-tune a decision. The biggest value I see however is, that decision logs can prevent repeating costly mistakes. Consider them as a safety net as powerful as 100% automated test coverage. In order for that to work though, you need to write proper decision logs. I’ll tell you how.
How should they look like?
Every decision log template out there contains when, who and what decision were made. This in itself is of limited use. If I can say in 2021 “Aha! Using the stupid library that always breaks and is undocumented was a decision by Trever on 2012! I’ve never met you Trevor, but damn you!” I will briefly feel better (Hey, it’s all Trevor’s fault!), but looking up the decision didn’t bring any value for the business.
A good decision log template, I personally like the Atlassian one, therefore includes at least
- Who was involved in making the decision (who consulted and who actually decided). Use full names and titles. Nobody will remember which “Max” vetoed a decision 5 years later: “Max Smith (Head of Accounting)”
- When was the decision made. I suggest international date format YYYY-MM-DD: 2012-01-31.
- What was decided on: “From now on we will only use open source operating systems on employee PCs.”
- Which alternatives were considered / what was NOT decided on
- Why was this decision made: Pro & Con list for all options, cost of all options
- Whether one option was vetoed / immediatelly excluded for some reason
- Whether parts of the decision were postponed or split off the main topic
Pick a structure that works for your team and stick to it. For decision logs to become a valuable tool, they should keep their general structure over the years.
Pro & Con lists
I have highlighted the most important parts of the decision log. Don’t focus so much on the outcome of a decision (which often is evident in the system anyway), but on the stuff you did NOT implement.
|Option A||Option B||Option C|
|– License not compatible with project||+ Well-documented and widely used|
– Rather expensive (details below) enterprise account necessary
+ License is ok
– No documentation
Every small decision is a potential mistake. If its logged property, you can fix that mistake with confidence, because you know why the decision was made. Relevant insights include
- They never even considered option X? If they had, they would have picked it. I’ll change it now.
- I wanted to replace option B with option C, but the drawbacks mentioned in the decision log still remain. That saved me some time.
- The license was the only reason not to choose option A? They have recently changed the license, let’s re-evaluate!
Which decisions should be logged?
There is a general consensus on logging large-scale decisions regarding infrastructure (Monolith or microservices? Amazon or Google?). That’s not enough! Nowhere near enough! The small day-to-day decisions are equally important: Which datepicker library should we use? Should we take the faster algorithm or the slower, more secure one? Those are the ones causing developers three years later to pull out their hair in frustration.
It’s hard to get used to create a decision log for the smaller things. Therefore use a checklist of criteria:
- Dependency / library added. Yes, all of them. Yes, I’m serious. No, it doesn’t happen as frequently as you think.
- When you sign up your team / company to a service provided by a 3rd party. (e.g. creating an account with a payment provider, process management tool, image hoster, …)
- When you change the way your team works: New processes, coding style, guidelines…
- When you have a meeting with a new vendor. They want to sell you something. Whether you buy it or not is a decision, even if “there is no other alternative on the market”.
- After every “Spike”.
- Every time there is disagreement in the team, no matter how this disagreement is resolved (“Liza said a pre-push hook should prevent broken code, whereas Carl mentioned that the CI pipeline testing the code is enough. They went back and forth for hours until the boss told us to ‘Shut up and do whatever is fastest’!”)
- Every time the word “decision” pops up: “The management decided to scrap Project Horseshoe”
Does that seem like an insane amount of overhead to you? Try it out, in the end the frequence of these occurences if often overestimated. To help you handle the work, have a decision log template ready for different cases. For instance, if you frequently add dependencies and don’t have a choice about it, a decision log template with a text block “[TOOL] was chosen as it is currently the only option for [TECH STACK]” may make sense. Future readers that have more choice can then safely make a different decision.
Weight your Whys: Decision criteria
One crucial part of the decision log is still missing. Decision criteria makes all the difference between a helpful decision log and a useless waste of bytes.
Looking at an old decision log, you might be baffled that the pro & con list often does not seem to reflect the outcome.
|Option A||Option B||Option C (Picked)|
|– License not compatible with project (immediately ruled out)|
Cost: No quote requested
|+ Well-documented and widely used|
+ Guaranteed uptime of 99.99%
+ Great performance (tested under real conditions)
+ 24/7 support hotline
Cost: 3,600$ / yr.
|+ Considered to be the most secure option on the market|
+ Privacy settings can be fine-tuned
+ Guaranteed uptime of 99%
– No documentation
– Performance issues on peak hours
– Not compatible with current invoicing system, needs update to newer version
– Initial setup takes 4-6 weeks
Cost: 15.000$ / yr.
Looking at the list above, it is unclear, why option C and not option B was picked. Explaining the decision criteria helps:
“At the time of writing, we operate solely on the German market. Market research has shown, that security and privacy considerations are paramount in Germany. Therefore the decision was primarily driven by security and privacy aspects.”
If possible, add some numbers to it, similar to the way professional product testers do (“Support and documentation was 20% of the overall grade, security and privacy 50%, performance 30%”). Alternatively, you may be able to quantify the monetary value of pros&cons (Upgrading invoicing system: estimated at 55.000$; Waiting for initial setup, losses estimated at 10.000$ …)
If the decision criteria in the decision logs is clear, this will be especially helpful if the criteria changed – the company all of a sudden is flush with money? Wants to sell an in-house tool to outsiders? Operates in different markets? Abandoned their “green initiative”?
It is not uncommon that IT professionals are ashamed of their decisions. “Of course it was the wrong choice. But we had to rush this out! We were under pressure by our stupid boss and nobody wanted to work overtime right before the holidays!”
It gets even worse, if decision makers are ashamed of their decision criteria: “In the end, despite costs, it mattered most that the CEO of A Corp. went golfing with our team, but the guy from B Inc. was not. But of course I won’t put this in the decision log!”
Social networks, time pressure, limited information, company politics, a lot of non-technical factors drive and shape decisions. They must be noted in the decision log in order to keep the value of the tool. Don’t be ashamed of these factors, log them in a professional way. The “Nice fellow on the golf course” becomes “Access to top-management in order to resolve issues may lower long-term costs” – this is a valid and important criteria and if it changes in the future can be handled accordingly.
I hope this article was valuable to you. Leave me a comment if you like. If you need help setting up your decision log process, contact me.