Decisions should not be boring to read

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:

Eventually the impact deepens:

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

Now what?

Here is how to get started:

Further Reading