Keep programmers’ decisions documentation up-to-date and simple with Architecture Decision Records

Developing a system over years is hard, as is writing clean, maintainable, up-to-date code. But believe me, writing easy-to-maintain AND up-to-date documentation is not trivial either.

Once upon a time, I heard at a conference that software engineers are not good at making a long-term commitment to their code. We all love greenfields more than diving into decades-long bloated projects, sounds familiar?

But actually, that’s not true. At least not for every mature project. The difference is in the documentation.

Spooky storytime

Of course, code grows over time. Dependencies get complicated, and decisions made in the past that were once obvious can be completely indecipherable and puzzling to new team members.

Let’s take a look into 2 examples

1. The team had to choose an external service provider, a library, or a tool. The more popular solution looks better, but research has shown that a shared API fails to meet one of the key business requirements. In the future, the new team member will be tempted to question this choice, which can lead to wasted time and even inconsistencies in the application.
2. The QA engineer found a major bug 3 weeks before the critical production release. The desired solution would require significant changes to the data flow and involve a redesign of the system. Due to time constraints, a senior software engineer opted for a temporary fix to favour business value at the expense of maintainability. At the same time, the team agreed that the desired solution would be implemented just after critical release.

Without documentation, there is a risk that the team will not dare question the temporary solution in the future, believing that this decision was certainly justified.

In short, the decision can either be questioned or accepted blindly without justification. In either case, it leads to terrible scrapes.

Many teams have a senior expert who has been with the team “since the dawn of time” 🧙. The expert is the go-to person who remembers why the decision was made and passes it to other team members during meetings, via Zoom or Slack.

We all agree, that word-of-mouth knowledge transfer works well when it comes to personal development, but is unreliable for software development. So, shouldn’t we be ashamed to use such an analog, old-fashioned method in the high-tech industry?

That’s why we need documentation for the decision-making process, and we chose ADR. That’s why I’d like to convince you to write down ADR, too.

What is ADR?

ADR is an acronym for Architecture Decision Record.

And the next question is: What can be called an architecture decision?

Architecture is about the important stuff. Whatever that is.
~ Martin Fowler

An architectural decision can be defined as a response to a functional or non-functional requirement, a decision made before the implementation phase, that affects the quality of the system.

In short, I can paraphrase Martin Fowler, architectural decisions are the most important decisions that shape our application.

And in such cases, the ADR is our diary, the decision log we leave for ourselves and for subsequent software engineers.

Benefits

ADR enforces a useful layer in the software development process and provides your team with clear benefits such as:

• 🤝 mandatory team consensus — every decision must be approved by the team
• 🚩 documented current state of the system — only final and unambiguous decisions are recorded
• ⏳ linear history of decisions — previous decisions are not deleted
• 🚀 smoother onboarding of a new team member
• 📄 consistent documentation without mandating a form that is difficult to maintain
• 🧠 avoiding blind acceptance/reversal of a previous decision

Qualities of an effective ADR

• Shared — Information is readily available to those who need it.
• Brevity — Short and condensed information, rather than a long, time-consuming document for both the author and the reader.
• Reasoned — It provides the relevant context to understand a decision and challenge it if necessary
• Immutability — Once an ADR has been added and approved, it cannot be modified. Only the status can be changed to maintain the current state of the decision — valid, deprecated or superseded by another decision, etc.

When should I write ADR?

Well, I would quote here Spotify — almost always when the decision affects the development.

Do I have a problem? Yes
Is there a blessed solution? Yes
Is it documented? No
Write an ADR!

More about Spotify approach: When Should I Write an Architecture Decision Record.

The main role of ADR is to document the decision. It is not to assist in the decision-making process or to take minutes of meetings, but simply to document the final consensus that is deemed implementable. Every decision is a compromise: if something is obvious, irrefutable, there is no decision to be made and therefore no ADR. And what’s more, there’s no ADR without team communication.

Where should ADR be stored?

You may be wondering where to keep ADR. Since it is documentation by developers for developers, it should be stored as close as possible to the decision object — the code. That was the main goal for us at eCommerce Tabletop.

As long as we use a single repository, ADRs can be stored in the root of the repository and applied to all application modules, and that’s the approach we are taking in our eCommerce monorepo.

ADR template

There are many proposals for document templates that we can use as ADR. Historically, this problem has been addressed by the IBM UMF — Unified Method Framework (1998) or the Tyree / Akerman model (2005). However, they require many fields and are too cumbersome for me to maintain.

Nowadays, the most popular is the lightweight ADR model described by Michael Nygard (2011) and MADR — Markdown Architecture Decision Record (2018), which is an extension of the ADR model.

We have chosen to use the original, simplest 5-field template, which makes developing and maintaining a decision record painless.

• Title — The decision is identifiable by its title, and the numbering makes it easy to follow in linear history.
• Date — When was the decision introduced?
• Status — What stage of the life cycle is the decision in?
• Decision — The clear and concise decision with a description of what is being introduced.
• Context — Should provide the strategic background.
• Consequences — Positive and negative implications.

The decision life cycle proposed by Michael Nygard

Context

The context should answer the reader’s questions:

• Why was this decision necessary?
• What were the limitations in the context of this decision or the assumptions that led to this decision?

The context must be pragmatic. It can include key elements such as business priorities, organisational elements such as team experience, dependencies to the issue, time constraints to implement the solution, etc. You can also include other information here. Whether other options were considered and why they were rejected.

References

This is a common problem with documentation per se.

In the onboarding flow for the new team member, we need to include the information that we are using Nx Monorepo for our project, but should we also explain what the Monorepo is, how to create it, how to manage it, and in short, duplicate the Nx documentation?

The answer is no (we can prepare tl;dr, but that is optional).

Scattering information across multiple sources and duplicating knowledge bases are two important risks in creating ADR. To deal with this, it is necessary to maintain active links, references in the ADR. These may be references to other ADRs, other documents, functional requirements, articles, etc. These references must be sufficient to understand the decision, assuming the reader is not familiar with the background.

Additionally, if the new ADR replaces the previous one, it is necessary to link them. On the previous one, set the status to superseded.

Practical examples

Examples of real-world ADRs can be found in some open source projects:

• EdX, education platform in each repository doc/decision directory ​​https://github.com/edx/
• Arachne framework https://github.com/arachne-framework/architecture
• Mozilla Firefox Accounts https://github.com/mozilla/fxa/tree/main/docs/adr
• Tendermint https://github.com/tendermint/tendermint/tree/master/docs/architecture
• ADR tools https://github.com/npryce/adr-tools/tree/master/doc/adr

I hope these example will be inspiration for you and you find it helpful. Thanks for reading ~ Rita flynerd.pl.

Originally published at https://dev.fandom.com