Do you know this situation?

Important technical or architectural decisions are first discussed in great detail in the team and three months later the question arises as to why this technical decision was made, for example by a new employee or during a job interview, but no one can answer the question in detail, although the decision had previously been heavily discussed.

Everyone remembers the decision itself, but nobody remembers the whys and the hows. This has happened to me personally very often, both … as the person who asked and as the person who was asked. But the important question is, can you do something about it?

Fortunately, there is a surprisingly very simple solution.

Architecture Decision Records

The question of how to document technical decisions is not new. This question is quite old and it is all the more astonishing how few concepts and ideas there are for creating technical documentation in a systematic and structured way.

A method that I think is most efficient is called Architecture Decision Records (ADR) and was defined by

The idea is relatively simple. Write a document for each technical decision made and then keep those records, both the rejected proposals and the proposals that were eventually accepted.

Structure of ADR

There is an original proposal made by Michael Nygard, but based on this there are also different variants from other developers. But the basic structure is always the same. In general, each ADR should be described as neutrally and objectively as possible.

1. Title

Every ADR needs a title. This should be compact and clear if possible. I recommend numbering decisions in the title to create clarity like in a database.

2. Status

The status defines whether an idea/suggestion was accepted or rejected. Of course, outstanding decisions are referred to as “pending” or something similar. You can also implement further steps such as “pending, promising”.

3. Context

Other developers should be able to understand the context of the decision at any time, whether during the decision-making discussion or months afterward. The context results from the problem, the initial situation, and the condition.

4. Decisions

Here we define the idea of a decision and explain it within the framework of the context.

5. Consequences

The positive and negative consequences of a decision need to be recorded as well, which are to be determined through a discussion. If, for example, you have a suggestion for a microservice to write it in a programming language that is not yet used in the company, the negative consequence would be that some developers might first have to learn this programming language. A positive consequence could be, for example, that this specific programming language processes the incoming requests way faster than the well-known programming languages of the company.

Workflow with Git

If you manage the documents with Git, you could theoretically do without the status in the document, because this status then results from the status of the pull request or the status of the branch. As long as the PR is still open, a decision is only a proposal. Once this PR has been merged, the proposal is accepted.

Tools

There are also some CLI tools to deal with ADR, the most popular being ADRTools. I think that’s a bit overkill since there’s only one Markdown file per suggestion. Alternatively, you can simply create a template repository on Github, Bitbucket, or Gitlab and then build on it. How you manage your ADR is of course up to you and your team.

Thanks for reading my article about Architecture Decision Records. I hope, you could learn something new.

Cheers!