A little about the Architecture Decision Records approach
In the process of developing a design solution, we usually make many changes. No, of course there are projects where all the requirements are strictly “nailed” into the technical specifications and making any changes is almost impossible. But most projects, to one degree or another, use the famous Agile methodology, which allows for flexibility in the implementation of projects.
At the same time, we cannot always clearly determine which of the decisions we make in the process of work are architectural, that is, requiring mandatory documentation, and which are not, although they are also very important for the project. When software architecture evolves as a result of a team making a series of decisions, development teams need a way to track the architectural decisions they make. This is where the Architecture Decision Records (ADR) report comes to their aid. Essentially, ADRs are documents that describe the architectural decisions made in a project or system. They are used to store and transmit information about decisions made and the rationale for their adoption.
About the benefits of ADR
When considering ADR, you should not think that this is some kind of Western analogue of our GOST 34 series and similar documentation standards. In this case, it is more about making the decisions made during the work on the project more transparent, that is, understandable to the entire development team. ADR records help the team clarify what it is doing and why. At the same time, it is important to preserve this argument for people who will further support and improve the system.
When software architecture evolves through a series of decisions that are themselves born of hypotheses and experiments that test those hypotheses, development teams need a way to track the architectural decisions they make. Essentially, we need to record the decisions we make, as well as the arguments and assumptions that guided our decision.
However, some of these decisions may change over time, and the development team needs a way to easily analyze what was previously made. Even if they don't change, future teams will need to understand the options and trade-offs that were considered so they can make better decisions about system evolution.
Expensive architecture
As mentioned earlier, ADR does not have a clear standard similar to Russian GOSTs. It is clear that if we record literally every action and insignificant decision, then we risk receiving a large amount of completely useless information, so first we need to decide on those actions and steps that we need to document without fail. Thus, the ADR must document important decisions, that is, decisions that have architectural significance. We will talk in more detail about which decisions have architectural significance later.
Before that, let’s define concepts such as architecture and solution design and the differences between these concepts. Design, in relation to software development, is the area of designing and creating solutions, which is a complete description of the components of the implementation of a given solution and their interaction. Architecture, in turn, is a set of important design decisions that determine the form and function of a system, where significance is measured by the cost of change. Thus, all architecture is design, but not all design is architecture.
A design can contain many different solutions, but most of them can be inexpensive for the development team to change. For example, renaming a field in the application interface is not an expensive change, although it is also part of the design.
But if we want to change something in the architecture of our solution, then such changes can be quite expensive, both in labor hours and in real money. Let's look at a few examples of various expensive and not so expensive changes that are or are not architectural decisions.
The company is developing a custom application. This application has a window interface for interacting with users. Even when using a UI framework, changing visual components can be time-consuming and expensive, but it is rarely technically difficult unless the changes affect the fundamental concepts that the system operates on. That is, changes in the interface did not affect the application code, and therefore were not difficult from the point of view of developers, but were expensive, since each design change still required additional costs for the work of designers and testers. However, these essentially expensive interface changes are not architectural changes.
If, in the process of finalizing a microservice application, you decide to replace the framework on which a service runs with a more productive one, or rewrite the code of this service to add new functionality, then such a change will be an architectural change. Naturally, such changes can be expensive.
But there are still expensive, but essentially non-architectural changes. For example, replacing one major component or subsystem with another with equivalent functionality. An example of this would be moving from one database to another. Let's say we are making the transition from MS SQL to PostgreSQL. As long as the new component/subsystem supports the same fundamental concepts as the old one, the changes do not affect the system architecture. That is, if the structure of tables, directories and their connections remain unchanged, and the procedures change in terms of the commands and syntax used, but perform the same functionality as in the previous database, then in this case the architecture will remain unchanged. Although this change can also be quite expensive.
Changing programming languages may also have no architectural significance if the languages support the same abstractions and language concepts. In other words, changes in syntax do not have architectural significance, but changes in fundamental concepts or metaphors do.
Implementation details should also not be confused with architectural decisions. So the choice of user interface platform, SQL database, or programming language to use is an implementation detail, not an architectural decision. These are all important decisions, but they do not rise to the level of architectural decisions.
Thus, returning to the ADR records. Source code is not part of ADR, we do not commit the code as it is not part of the architectural solution. In ADR, we record the functionality performed by this code.
In other words, it is important to understand that changing architectural decisions is expensive, and architectural decisions also determine the fundamental nature or “shape” of the solution, which we interpret as the fundamental approach to solving problems defined by a set of requirements for defining system quality.
Composition of ADR
Now that we're clear on what constitutes an important architectural decision, let's look at what goes into ADR records. To store files with ADR records, the same Git repository is best suited, since then we will be able to save previous versions and access them if necessary.
There are several ADR record templates, some of which are more or less tied to the specifics of the solution being described. The following will outline the main sections of architectural records. Here is a list of fields that can be in one record
Field Status — in it we indicate the current status of this record, for example, the decision was proposed, accepted, rejected, outdated, replaced, etc.
In the field Context it is necessary to indicate what problem we see.
In the field Solution it actually indicates what changes we propose and/or implement to solve the specified problem.
And the field Consequences contains information about the overall impact of the architectural solution. Every solution has trade-offs and they need to be specified.
It is important to understand that the hallmarks of a good ADR are its rational filling, that is, the reasons for choosing this particular alternative, the pros and cons of various potential options, a comparison of functions, a discussion of costs and benefits, and much more. At the same time, the ADR must be quite specific, that is, each document must contain only one decision made.
It is also important when making additions to the document to include timestamps that explain when additions are made to the ADR document. This is especially important for aspects that may change over time, such as costs, schedules, scaling and the like.
Conclusion
Using ADR allows you to make the process of documenting decisions made while working on a project more convenient and useful from a practical point of view.
We invite technical writers who are just starting to document APIs and SDKs to a free webinar, which will take place on October 1. Registration is available via this link.
