Documenting decision making process

In one of the latest articles on Farnam Street Blog, I learnt about the concept of second-order thinking and Chesterton’s Fence heuristic. As a result, it made me think of one of the very common behavioural patterns in tech – you join the company when something is already built, you don’t see value in it, or you believe that it could have been done better, and you start either to remove, either to refactor services or architecture. What can go wrong here and how is it related to decisions documentation?

Chesterton’s Fence

When we don’t agree with what we see, we use to think that someone did it without knowledge of best practices, or without understanding how things should be done.

For example, we refactor or remove components and services. As consequences, we can break something, the existence of what was even unknown for us. Or we start implementing a new solution and only in the process we face challenges which point us to why it can’t be done in this way and why it was done as it was done.

So what is the Chesterton’s Fence? In his book The Thing, G. K. Chesterton explained that fences are built by people who carefully planned them out and “had some reason for thinking [the fence] would be a good thing for somebody.” Until we establish that reason, we have no business taking an ax to it. The reason might not be a good or relevant one; we just need to be aware of what the reason is. Otherwise, we may end up with unintended consequences: second-order effects we don’t want, spreading like ripples on a pond and causing damage for years.

Should we never remove the fence?

However, I’m not talking about never questioning the status quo. But just following a few steps can prevent us from wasting time, money and creating unexpected consequences.

• Make the assumption that person who built something, knew what he was doing and made it with good reasons
• Try to understand WHY he did what he did in exactly this way
• Change it only when you know why it was done this way in the beginning, otherwise accept the risk that consequences of this decision can have consequences

Decisions documentation

What kind of documents is typical for an IT company? API documentation, RFCs, architectural documents. Typically doesn’t mean that everyone is following that, hehe. Unfortunately. But most of them are covering the current given state, and not explaining the thinking process behind. There is one specific type of documentation which is answering important questions: not only what and how but most importantly WHY and what were the other options – Decision log document.

The purpose of the decision log is to explain every option, their pros, cons and risks. It contains information about which decision (from the set of options) was made and why. As an example, you can check a great template for decision log in Confluence from Atlassian.

Let’s consider an abstract example of architectural decision for a new project

	Microservices with separate repos	Microservices with monorepo
Description	The current solution consists of 3 microservices in separated repositories and with separate CI/CD pipelines.	Proposed new solution to combine them in one monorepo to solve the problem of breaking changes and separate releases
Pros	Quick independent deployment	Safe deployment of interdependent services
Cons	Error prone synchronisation when contract has changed	Longer time to production, even for small independent changes
Outcome	Was decided to leave solutions with separate repos.	To solve the problem consumer-driven contract testing will be implemented between these services. Additionally, automated tool for simultaneous deployment will be implemented

To sum up, documenting all major architectural decisions can be as a time machine for those who will doubt this decision later on. And can simplify second-order thinking for our future generations.