Defining Architecture Decision Record (ADR)

With time and the evolution of technologies, building software has become faster but more complex in the same proportion. Therefore, tools that organize and mainly document software architecture decision-making are more than welcome. This article will introduce you to what architecture decision records (ADR) are.

But let's take a step back and talk about agility and complexity in software development. It is mainly due to two factors: the changing role of software and its nature. Next, let's see them in detail.

The Changing Role of Software: Software as a Means to an End

In the early days of application development, software emerged with the sole and exclusive purpose of processing data. At that time, hardware was a point of greater attention, mainly due to its cost, and consequently, this made the use of this technology not very accessible.

With the economic and technological evolution, software stopped just processing data and started to play a strategic role; information systems emerged, where this data processing began to assist in tasks and decision-making in companies.

In parallel, technological and economic changes continued to happen. Hardware was no longer a determining factor, which made the technology more accessible. The software started to be used massively and is no longer a privilege for a few people, becoming a factor of innovation and competitive advantage for those who used it.

This new vision has changed the way software is made. The need was for development to work quickly and consistently so that changes didn't adversely affect the business. Thus, agile methodologies emerged to accelerate and facilitate deliveries and changes during software development.

The Nature of Software: Fickleness and Evolution

We can say that software has three characteristics: complexity, ephemerality, and mutability.

• Complexity: Software is not just code; it involves technology, people, processes, and business.
• Ephemerality: Technologies come and go daily. A feature or entire software can become unfeasible/obsolete from one moment to the next, whether due to a deprecated technology or a mapped vulnerability.
• Mutability: It becomes essential for the software to keep working. You have to evolve constantly.

After All, What Is Architecture?

One of the most Homeric discussions in software engineering is undoubtedly the definition of architecture. In summary, and without controversy, architecture is the organization, communication, and structure of all software and services in an area and it nurtures the technological vision.

Decentralized Model for Success!

Over time, different methodologies emerged and replaced others. It is the case, for example, of Management 3.0, which condemns Fordism or the top-down model and values a model with more participation through six points:

• Energize people
• Empower teams
• Align constraints
• Develop skills
• Grow the structure
• Continue to always improve

Leadership needs to control the environment, not the people, and provide all the necessary conditions for the activities to be carried out in the best possible way by the individuals and thus maximize the results.

This leadership model doesn't just make sense for people management but also for software architecture. After all, how do you ensure that the entire structure works with a single person controlling it?

Of course, there is no software or a single person capable of guaranteeing good governance. After all, there's no escaping Conway's law. Therefore, a distributed architecture needs to consider that the team is well distributed and has autonomy. In other words, if the organization is messy, it will be reflected in the software.

Replacing “Do It!” With “Does It Make Sense?”

Over the years, it has been possible to perceive the various attempts to have just one person as an architecture professional or a single sector responsible for the architecture. But, these approaches failed miserably, which yielded only good jokes:

• “Ninja architect”: Disappears at the same speed as it appeared.
• “Master of wizards”: It has the title but disappears in the most critical moments.

It is always worth mentioning that the most significant role of architecture professionals is to choose the trade-offs of architectural decisions. Context is the key to any strategic decision at a technological level.

Another point comes from the book Skin in the Game, which says that we are more afraid of making a wrong decision when it also impacts us. Not to mention that software is constantly evolving and adapting. We learned that with the Agile Manifesto, a good decision today may not be a good decision tomorrow.

The solution is eternal surveillance of all teams as software architects. Thus the responsibility for the architecture is not a single person but the entire team, including its maintenance. Erik Dörnenburg confirms and reports this in his presentation Architecture Without Architects.

You need to follow a decentralized model to solve this problem. And today, it is possible to observe a high adhesion with positive results. For example, in the book Software Engineering at Google, a section condemns the myth of a single genius.

If we focus on the other extreme, we will undoubtedly fail. After all, if everyone can make decisions, this can result in a mixture of solutions with a high degree of complexity. Ruth Malan defends the role of architectural professionals, however, as facilitators.

Documentation, Decentralization, and Inspiration: The Best Match for Your Architecture's Scalability

There are several fallacies and myths in software engineering, and I am convinced that self-documenting code is on that list. We need to make suitable code fluid and close to the ubiquitous language. However, this does not exempt us from documenting our code.

In other words, it is necessary to perform clean code good practices, such as meaningful names, method size, smaller cyclomatic curve, and apply domain-driven design (DDD), among other reasonable procedures. It is just part of the job of writing good code, not the whole thing.

There are multiple examples of good software that preach the importance of documentation, for example:

• Java
• Golang
• Hibernate
• Quarkus
• Kubernetes

Big software companies like Red Hat have guides on documenting their software. In addition, there are professionals with this qualification: technical writers.

Today, good software documentation is as critical as testing.

The documentation guarantees scalability for your architecture and makes the decisions and their fundamentals clear to everyone, without the risk of getting lost over time or with the departure of someone from the team. For architecture, this goes beyond. It's not just quality but defines where we are, what we went wrong, and where we want to go.

Andrew Harmel-Law, in his article on architectural scalability, defends a way of working with architecture based on four principles:

1. Architectural advisory forum: This conversation could be a forum or a weekly meeting.
2. Lightweight architecture decision records (ADR): A place to store architectural decisions.
3. Team origin principles: An inspiration to unify the goals of architecture.
4. Your own tech radar: Your technology stack and sensors indicate the temperature of your technology.

What Is Architecture Decision Record ADR?

In this architectural context, a little mentioned point is the ADR. It is a document that captures architectural decisions with context and, most importantly, their consequences.

There is no standard for establishing this type of decision. It is already present in languages such as Java, with JEPs, and in software specifications such as Jakarta and the more “trivial” architectures.

Regardless of the format, a suitable ADR needs to meet the following requirements:

• Be simple to write and maintain. After all, if it is difficult to create/maintain, ADR tends to fall into disuse or become obsolete quickly.
• Consist of a sustainable architectural decision: Avoid repetitive effort and be strategic, realistic, and measurable.
• Be clear and objective about your objective.

The Basic Structure of an Architecture Decision Records 

Therefore, an ADR document should generally contain the following fields:

• Title: Something declarative stating its purpose. 
  • Tip: Start incrementally, i.e., 01 title, 02 titles, etc.
  • Separate by year, something that is easy to search and sort chronologically.
• Date: The day of the document.
• Status: The state of the ADR can vary by organization. Think of: draft, reviewed, approved, or disapproved.
• Context: The explanation of the fact and the context in a rich, direct, and straightforward way.
• Decision: The conclusion that was made based on the context.
• Consequences: Based on what we understand about architecture, what are the trade-offs of this action? It is essential to list all the results. After all, architectural decisions are based on study and analysis, and highlighting a previous survey is very important.

Example

Below is a simple example of the structure of an ADR:

1. Record architecture decisions

Date: 21.07.2017

    Status

Accept

   Context

All our decisions, studies, and architectural planning will be documented from an ADR

    Decision

A simple ADR model will be used


   Consequences

All of our decisions must be written, reviewed, and translated to ensure clarity, transparency, and scalability in our architecture.

It is just an example; it's not definitive. You can add and remove fields according to your organization's needs.

Conclusion

As in the software world, a scalable architecture ensures that the most significant number of architectural professionals perform this activity without breaking or shifting focus. In addition, it allows decisions to be taken assertively, avoiding change or blind acceptance, something recurrent in projects with history and context that is not adequately mapped.

Assurance that everyone is moving in one direction is certainly good documentation.

References

• Agile Manifesto
• Domain-Driven Design: Tackling Complexity in the Heart of Software –  Eric Evans:
• Management 3.0: The Book by Jurgen Appelo
• Scaling the Practice of Architecture, Conversationally – Andrew Harmel-Law