This is how we do it now!

When we work on our projects, we face the challenge of translating our clients’ requirements into a specific solution. It is not uncommon for us to lack all the necessary information at the beginning or for things to change along the way. So everything we do takes place in the context of known and unknown knowledge and ignorance. In this context, we make decisions that significantly shape our work.

While we are all working together as a team on the project, everyone participates in the discussions that lead to decisions. At the end of a meeting, it is determined: “This is how we do it now!” This means:

• How: We have made a decision.
• We: Everyone was involved, everyone is informed.
• Do: Something will change (or not).
• It: That’s exactly the point!
• Now: What we have talked about and discussed is valid right now.

In short: we know the decision, we implement it and thus manifest it. We can assume that it is obvious somewhere, for example, in the source code of our application. All is well.

All? Well, almost. In some cases, we might still want to justify the decision and write something for the posterity.

For the posterity? Yes, I hinted at it earlier: things change. A very simple example of this is a change in the team. Someone joins or leaves the team. Both of these can pose challenges with respect to our decisions:

Someone new coming in doesn’t know the context yet and the history is not apparent. Missing the beginning means being confronted with a certain status quo and having to make sense of it, seeing decisions being implemented without understanding the motivation behind them. Anyone who has ever turned on an exciting blockbuster movie on TV at 8:45 in the evening can easily relate to feeling quite lost. Fortunately, there are other team members who didn’t miss the beginning and can be consulted for guidance.

Wait a moment. Let’s remember: team changes can also mean someone leaving the team. And with each person who leaves the team, a piece of “historical” knowledge is lost. However, since we work closely and communicate a lot, even across project boundaries, this is not a huge problem. We will somehow figure out who was involved in the project (and thus in the decisions) and can inquire.

It’s somewhat like me asking you about a movie you watched a few years ago, as I heard you’ve seen it. That’s enough for me to consider you my expert. From now on, I will pester you with details of any scene I didn’t quite understand.

Will that work? Probably not. A lot of time has passed, and you’ve seen many other movies in the meantime. With luck, you may remember the crucial scenes in the film, but the scenes that were important to you may not necessarily be the ones I find confusing later.

The same goes for our projects. We change our context (even if we stay in the project), and time passes. Eventually, we can’t remember every detail, associated decisions, and the reasons behind them.

In other words, the posterity for which we want to write things down is ourselves. When I make a decision today, it’s wise to document it for my future self today (or at the latest tomorrow). Then, I can also explain why and with what knowledge, against what background, things have developed. Especially, when some aspects change significantly again, it can be helpful to refer back to earlier decisions.

What information should we ideally capture for this?

It’s a bit like the five Ws of emergency calls:

• Who made the decision?
• When was the decision made?
• What was decided?
• Why was the decision necessary in the first place?
• What influenced the decision?
• What are the consequences of the decision?
• What is the status of the decision?

You can consider these as a minimal set of information to record. Once you’ve captured all of this, you have created a strong foundation. In some cases, it may also be helpful to capture additional information:

• What alternatives were considered?
• Are there further details, such as meeting notes?

This form of decision documentation is an essential part of software architecture documentation. For example, architecture decisions are explicitly included in the arc42 Template (Section 9 of the documentation provides valuable tips for implementation and recommends a template).

A widely used structure for documenting decisions is the one proposed by Michael Nygard, which is very clear and straightforward: an “Architecture Decision Record” answers the above questions by providing information on the following points:

In addition to this structure, there are many other templates available. Joel Parker Henderson has compiled some of them in a GitHub repository, along with examples and further guidance. Some templates include more information, potentially making them more challenging to maintain but also more informative.

We find that the decision of whether to use a specific template for decision documentation is made within a certain context and is not free of consequences. Once you’ve chosen a structure, the next question is: in what format and where should we document our decisions? Should we store our Decision Records in a Git repository and use version control to keep track of decisions along with the code, so that we always see the most current and valid decisions at a glance but can still look back in history? Or should we opt for idempotent decision documentation, meaning a decision once made and documented remains unchanged, except to be replaced by a new decision? Should there be housekeeping rules for eventually deleting or archiving outdated decisions to keep the documentation more manageable? And what exactly constitutes a decision that must be recorded with an Architecture Decision Record?

We’ve chosen a rather pragmatic approach:

• We start with the structure proposed by Michael Nyberg. We add the date, decision maker, and topics or keywords. We also categorize our decisions into rough categories and if they become too numerous, we could separate our Decision Log accordingly.
• Each decision is documented on its own page in our wiki and the decisions themselves are also presented in an overview along with the status and date.
• If we see the need for additional information for individual decisions, we simply add it to the wiki page under the structure points. This can include pro and con tables for different alternatives, discussion notes, more detailed concept descriptions, or even just links to meeting notes. Whatever might be relevant in relation to a decision is recorded there.

With this structure, we have been doing quite well for some time. Partners who have joined the project later have been able to gain a good overview based on the recorded history and quickly engage in technical or business discussions with informed contributions.

In fact, we like to discuss, and the question, “Do we need a Decision Record for this?” has become second nature. In most cases, the answer is “Yes!”

But is there a rule of thumb for what must be documented as a decision and what should not? The article Gut dokumentiert: Architecture Decision Records:

“Gute Anzeichen für die Notwendigkeit der Dokumentation ist, wenn eine Entscheidung von bestehenden Best Practices oder eigenen Standards abweicht oder ihr lange Diskussionen vorausgegangen sind.”

In English, “A good sign of the need for documentation is when a decision deviates from existing best practices or your own standards or when it has been the subject of lengthy discussions.”

We can confirm this: in the early days, we might have discussed some things, agreed on them, but didn’t immediately write them down. The result was that we later had the same or similar discussions (perhaps with new context). Those were moments for reflection on the decision – and documentation.

We do it now. So!