Decisions should not be boring to read

Published on Thursday, June 24, 2021

TL,DR; Decision logs should be optimized for reading, not for writing. Make capturing them easy, ensure they are fun to read, do not limit it to architectural decisions only. A basic log of decisions Today is more useful than a perfect log Tomorrow

Have you ever looked at a domain model or an implementation of it and wondered: Really?! What were they thinking 🙄

I certainly have found myself in such a position in the past. Often it turned out that I had been the person who had taken things into a particular direction. However, the details of the decisions I had made in the past – which resulted in the current domain model – were no longer present in the forefront of my mind.

Although things might not seem reasonable at the moment: chances are they were at the time when the decision was reached to pursue a particular path.

Unfortunately it is difficult to understand things from a historic perspective when the current artifact of the model is all you have. This is further complicated when the people that once worked on the domain model have moved on to other areas of the organization. Perhaps they have even left the organization altogether.

Think about it… When was the last time you felt that you had poor situational awareness due to a lack of historic perspective?

The thing is that in some cases we make explicit decisions. But in others we continue on a path that existed already. I’m not saying it is mindless, it’s a natural thing to do. But it doesn’t always produce the best results. In an attempt to make things comprehensible and useful we have to challenge ourselves and others.

Here is what I have often heard after starting a “fact-finding-mission” and asking “What about this, or that? How come things evolved into this structure?”:

Hmmm, that’s right. That is odd. What you describe sort of emerged. We never really decided to head into that direction.

– Another (former) model contributor

Wouldn’t it be great if we could understand the environment of our domain model when it was conceived? What would happen if people would be forced to think about the decisions they make regarding the software design; the process; the collaboration with others; and the business model implications?

Imagine… Reading through the history of a project in 30 minutes or less

What if today you would start to capture decisions that you make on a daily basis? In writing, optionally enriched with graphs and maps. What side effects would that produce? And how would you benefit from doing so in – let’s say – three to six months from now?

Here is what I think will happen:

The act of describing and announcing your intent to capture decisions explicitly, will start a conversation with members of your team about the decisions we take on a day-to-day basis;
Awareness of the impact of implicit decisions will rise;
Reviewing work of a team member (e.g. in a pull request) will become easier when that work is accompanied by a list of decisions that explain the reasoning behind the work;
When a change is not guided by a decision that provides the arguments in favor of it, then members of the team will more often prompt for an “explicit” decision. This extends beyond software changes. Ideally a modification of the Scrum/Kanban/… process, the introduction of a new collaboration technique, or a change in strategy, should also trigger the request to capture the underlying decision;
Decisions that are poorly understood will often reveal assumptions that not everyone shares or agrees on;
The common language (i.e. ubiquitous language) will be reinforced and become richer because logging decisions requires us to express our domain models in writing. The decisions themselves might be a place to “mine” for new terms and expressions that should enter the common language of the team and be represented in the code artifact;

Eventually the impact deepens:

It will become easier to deal with people joining or leaving the team. The important how and what questions are contained in the combined list of decisions that were created as a collective;
Team members that get stuck will be easier to reignite by reading through the history of what was collectively decided. If the situation is overwhelming you could decide to reduce scope or size in one way or another;
The principle that it is okay to change your mind will become embedded within the team’s memory because when needed the team will revise a decision. The team overwrites a prior decision with a new decision that is made with more situational awareness and the team feels good about it rather than sloppy;
Trade-offs between one thing and another will be at the forefront of discussions because trade-offs are frequently at the center of a decision. This reduces dogmatic thinking in the team;

Does that seem unreasonable? Does that sound too good to be true..? Perhaps, but no-one was ever able to say that some kind of food wasn’t tasting nice without actually tasting it. The best way to get started is… To get started.

A basic but useful approach to capturing decisions in tech teams

To get started I propose something simple: Log your decisions in DECISIONS.markdown files in your version control system.

Start with a single file in the top level directory. Optionally add other DECISIONS.markdown files in sub-directories. Adding more files comes at the price of spreading information, make sure that it is evident what inventory of files exists. For example by maintaining an index.

As a rule of thumb you could say that at least each team should have its own DECISIONS.markdown file. In an ideal world that would correspond to a clearly defined section in the codebase (or a bounded context in case you are practicing DDD).

Stick to a minimal structure and evolve it when needed. My minimal structure is a heading for the day followed by a list of bullets with the decisions of that day. One way to evolve it is to group decisions by type when lots of decisions get taken on one day.

Good Examples

Here is what I consider good examples. Good because they provide just enough context; are easy to read and comprehend; use the language of the organization; and talk about real problems.

Tuesday, June 22nd, 2021
========================

 * Working with Marijn is not fun when he is hangry. 
   Make sure to lunch in time.
   
 * Access to customer is limited until Thursday July, 8th. 
   Model a naive happy path first and only implement that.
   
   Until we have verified the approach with the customer,
   ignore edge cases and model enforcement.
   
 * To prevent maintenance hell (we don't want another Project X)
   the product will not allow customer specific extensions.
   
   If specific needs cross our paths, look for an abstraction 
   that may serve other customers (different) specific needs.
   Be mindful of abuse in that model (e.g. a `comments` field).

What not to do

Do NOT be dogmatic about structure or form: Formats suggested by Architectural Decision Records are great training wheels. What they fail to recognize is that it is incredibly boring to read more than five ADRs in a row. They are too repetitive.

In my opinion decisions should be optimized for reading rather than writing. The goal is that these things will be read in order for them to frame our perspective.
Do NOT capture a decision that cannot be translated to team behavior: Each decision should inform how the people involved with the project act.

A good decision provides people with the context how they are supposed to behave in a particular situation.
Do NOT change your decisions (outside of correcting typos): Although it is tempting to apply what we learned today on our views of the past, you should not be forging history.

Capture whenever you change your mind in a new decision.
Do NOT postpone capturing decisions in order to get it right: Getting everything set-up perfectly; training your team members on the importance; publishing to a central location; Although useful, it shouldn’t keep you from getting started.

A basic log of decisions Today is more useful than a perfect log Tomorrow.
Do NOT ‘translate’ the decision after it has been made: If the decision was made using a common language of a group of people, then you shouldn’t obfuscate that linguistic abstraction to make it digestable for people outside that circle.

Capture decisions in the same dialect that was used for reaching the decision.

Now what?

Here is how to get started:

Reflect on the work of the last 4 weeks: what decisions have you made? Can you capture them in a non-boring format?
Introduce files for capturing the decisions and make the first decision that you want to capture decisions from now on. I am tempted to provide you with a template, but you need to find your own voice. Make sure that it is fun and that people understand it.
Look for hidden decisions in Pull Request comments and other Communication tools; Log those decisions yourself. Comment that you have logged the decision. Potentially make a mistake to get people to help you.
Schedule a meeting with yourself in 4 weeks to reflect on the decisions that have been captured by then. What have you learned? What hasn’t been logged but should have been? What can you do to improve that in the future?