Author: Ni Xinming

ADRIt is a very cost-effectiveArchitectural decision documentation practiceThe cost of introducing and practicing the team is very low, but it can bring great benefits to the team!

1 The problems faced by the team R&D

Whether it is in the traditional IT industry or the Internet industry, R&D teams at the architectural decision level will have more or lessFace the following issues or challenges:

•When new members join the team, they may have opinions on the existing architectural decisions of the systemBlindly complyKnow only the what, not the why; orChallenges or violationsConstraints, continuous challenges to the current decision, question the rationality and correctness of the decision, and the person in charge needs to continuously explain, synchronize, and promote consensus

•The potential problems of architectural decisions are exposed over time, butIf these issues are fully analyzed during the decision-making process, they may be discovered and avoided in advance

•The existing system architecture decisions areHow will it evolve?What is behind the current decision?What is the motivation?Is it possible that there is no one in the team who can accurately answer?

•Similar architecture decision scenarios in the systemRecurring，due to factors such as forgetting the reasons for the decisions or changes in team members, it still takes time to analyze, design, and promote stakeholders to reach a consensus

•within the teamOnly a few people are responsible for architecture design，other team members have no opportunity to participate, but in factTeam members have corresponding demands，at least you can understand the decision-making process of a key architecture design

•Even for projects taken over internally by the team,Can you quickly obtain the key architecture decisions of the system and their reasons？You may look for clues about architecture decisions in the code repository, but it is difficult to obtain the motivation behind the architecture decisions and the evolution process of the decisions

Based on the above issues, we want to:

•ThroughMinimal but still efficientA way to record the system's architecture decisions

•CanIdentify the evolution process of key system decisions

•Architecture decisions and design best practices can be shared among teamsEfficient synchronization

•All team members have the opportunity to participate in the architecture design decision-making process

The primary issue in recording architecture decisions in written form is:Document obsolescence！！

Indeed, the issue of becoming outdated is an inevitable problem in documentation. Regardless of the mechanism, such as strict processes or automated updates, there is always a risk of becoming outdated. So why choose to record architecture decisions? Based on the following two reasons:

•Cost-effectiveness: The benefits of documenting architecture decisions far outweigh the costs of maintaining outdated information

•Lightweight: Keep ADRs short and lightweight,The smaller the document, the easier it is to maintain synchronization with the actual situation.

2 ADR analysis

Architecture Decision Record，abbreviated as ADR, namely Architecture Decision Record, this practice was initiated by Michael Nygard, and it is one of the most effective ways to record architecture decisions. Simply put, ADR is a documented record of architecture decisions, whichThe purpose is to record the system architecture decisions, reasons, and decision-making process in a documented form.

By effectively recording system architecture decisions, the team can benefit from the following aspects:

•Newcomer guidance, making it easy to quickly familiarize with the new system, new team members can quickly obtain the historical architecture decisions of the system, understand the background, decision-making process, and related impacts behind the decisions

•Project handover, documenting existing decisions, Agile environment emphasizes the team's rapid learning of knowledge, and based on ADRs, the team can quickly familiarize themselves with the architecture evolution process of existing systems

•Aligning cognition through promoting the implementation of ADRs makes it easier for team members to reach a consensus on the best practices in design, further avoiding the 'reinventing the wheel' in the subsequent construction process, and enhancing the reuse of design knowledge among teams

SuggestionThe basic structure of the ADR includesTitle, status, background, decision, and impactThere are five parts in total, generally speaking, it is recommended to addConsistency and notesTwo additional chapters of great value as supplements.

It should be noted that,The team can add other chapters as needed to enhance the performance capabilities of ADR., such as adding an optional solution chapter to provide a detailed description of the optional solutions.

Title [Optional]

The "title" part of ADR mainly includes two parts: one is the sequential number, and the other is a brief description of the architectural decision. The description of the title needs to ensure the accurate and clear description of the architectural decision, without ambiguity, and alsoKeep it short and clear.

For example: ADR 01. Adopt asynchronous message mechanism between order service and fulfillment service

Status [Optional]

The "status" of ADR is limited to Pending Review, Approved, ReplacedOne of the three states.

•Pending Review: The decision must be reviewed by senior decision-makers or ARB

•Approved: The architectural decision has been reviewed and is ready for implementation

•Replaced: The architectural decision has been changed and replaced by another ADR. This state indicates that the previous ADR must have been reviewed and approved, and ADRs in the proposed state that have not been reviewed and approved are not allowed to reach this state. ADRs in the proposed state can only be modified until they are approved.The replaced state provides an effective architectural decision traceability mechanism, which can help the team identify the evolution process of architectural decisions.

Background [Optional]

Promote the architect to think about this itemDescribe the specific background or problem of the architectural decision, and briefly state the possible optional solutions. The decision background is also a description of the system architecture to some extent.

Note:Not recommendedThis chapter provides detailed analysis and explanation of the alternative solutions, and if a detailed elaboration is indeed necessary, it is recommended to add an additional chapter for explanation.

Optional Solution [Optional]

Provide a detailed description of the optional alternatives and compare the advantages and disadvantages of different solutions

Decision [Optional]

This part includesSpecific architectural decisions and the corresponding decision basis, it is generally required to use positive and imperative descriptions to express specific architectural decisions, and there should be no subjective, negative, ambiguous, or potentially ambiguous wording. Note: Focus on Why rather than How, understanding the reasons for architectural decisions is more important than understanding how to implement them

Impact [Optional]

This part describes the overall impact of this architectural decision.Each decision will have more or less impact on the existing system, including both positive and negative impacts, and promote the architect to think about these impacts through this chapterWhether it exceeds the benefits of architectural decisions.

Consistency [Optional]

This part is not an element of the standard ADR, but it is also quite valuable,Its role is to promote the architect to think about how to measure and govern the architectural decisions from the perspective of architectural consistency.The architect must determine whether the consistency guarantee of this architectural decision is achieved through manual or automated means. If it can be automated, the implementation plan of automation should be clearly stated in this chapter.

Remark [Optional]

The remark section is not part of the standard ADR structure, but it is strongly recommended to add this chapter. The remark section mainly contains various metadata of ADRs, such as:

Author, review date, reviewer, alternative date, last modification date, modifier, last modification content

Explanation: Some teams believe that metadata information in the remarks section is not very valuable, especially when teams store ADRs with code in the configuration library (not recommended). However, in fact,Including metadata as part of ADRs is more valuable and advantageous than relying on configuration libraries.

3 Organization and Storage of ADRs

The specific location of the ADR document, such as FTP server, WIKI, or the same project code configuration library, can be flexibly chosen by different teams according to the situation. Principle: ADRs can be easily accessed by stakeholders.

Method One: Based on a configuration library similar to Git

Advantages:

•Architectural decisions are close to the code, convenient for developers to access

•Easily implement ADR change management through the version management capabilities of the configuration library

Disadvantages:

The stakeholders of ADRs are not only developers but also other project stakeholders such as technical managers, product managers, and business personnel. Storing them in a highly technical configuration library is obviously not friendly to roles other than development. At the same time, it is also necessary to open repository permissions for non-developers, and code security is also a factor to consider. Additionally, storing in a configuration library is not convenient for storing common architectural decisions for different applications within the same system and integration architectural decisions between applications.

Method Two: An online collaborative editing and sharing system similar to WIKI

Advantages: Friendly to stakeholders, convenient for online collaboration and handling cross-application architectural decisions

Disadvantages: Unfriendly to developers, far from the development library

Based on the storage of cross-application architectural decisions, the team chooses to store ADRs on an online collaborative document platform and organize them through a reasonable folder structure. Refer to the following organization form:

4 ADRs integrated into the development process

If ADRs are to be implemented, they must be integrated into the existing development process. The main process activities covered by ADRs are:

Formulate ADR

•Activity Name: Formulate Architecture Decision Records (ADRs)

•Prerequisites: None

•Stakeholder Responsibilities: Subsystem leaders are responsible for formulating ADRs within the scope of subsystems, and system architects are responsible for cross-system architectural decision-making

•Activity Input: PRD activity output: 'Architecture Decision Record'

•Execution Form: Offline, or informal brainstorming

•Execution Time: A sub-activity of system design, carried out during the system design phase

Review ADR

•Activity Name: Review ADR

•Activity Purpose: Review the completeness and correctness of ADRs to ensure the rationality of architectural decisions

•Prerequisites: ADR development completed

•Stakeholder Responsibilities: The ADR appointee initiates the review, and system architects and core developers participate in the review activity

•Activity Input: ADRs

•Activity Output: ADR review record (update review information on the ADR document)

•Execution Form: Formal or informal review meeting

•Execution time: When conducting internal review of the technical solution, review the ADR related to the solution

5 Common questions in the ADR practice process

Question 1: The 'high time cost' of writing ADR, which prolongs the technical solution design cycle?

Answer:No!

This question may mainly come from the following reasons:

•Writing documents = time-consuming? Most R&D personnel reject documentation and do not have the habit of writing documents.

•Insufficient understanding and accuracy of the ADR template, and no way to start writing during the writing process

•Lack of necessary analysis habits, lack of necessary comparison and analysis in architectural decision-making, lack of necessary basis in writing ADR, and having to look up additional materials, so it takes 'a long time' to write

But in fact, if the architect has the habit of decision analysis, especially when designing technical solutions, and has conducted sufficient decision analysis,Writing an ADR document of 1-2 pages will not take more than an hour, even in half an hour. Even if the development and review of ADR affect a small part of the design time, the value brought by thorough analysis and re-evaluation of key decisions far outweighs the additional cost caused by rework

Question 2: Is it necessary to write ADR for legacy systems?

Answer:No!

Value is one of the factors that determine whether to write ADR, but beware that ADR should not only record current architectural decisions. For legacy systems, recording key architectural decisions before the team forgets them still has great value.

Question 3: Does the ADR documentation mechanism conflict with agility?

Answer:No!

The Agile Manifesto states: working software is preferable to comprehensive documentation. It emphasizes the value of the left side, but does not deny the value of the right side.

Therefore,Documenting does not necessarily conflict with the agile concept.By adopting a lightweight document mechanism, record things of core value, ensure that the document mechanism will not become a burden for the team, and itself is in harmony with the agile culture.

Question 4: Is the ADR review process too heavy?

Answer:Maybe, but it is necessary!

ADR review is one of the important activities for introducing the ADR mechanism and should not be ignored!It is precisely through the review activities involving multiple stakeholders that the many important values of ADR can be realized. Through this formal or informal review activity:

•Enhance the rationality and correctness of architectural decisions

•Enhance the technical atmosphere of the team

•Enhance the technical thinking ability, technical level, and involvement in architectural decision-making of team members, and achieve efficient synchronization of architectural decisions among team members...

Therefore, the review activity of ADR is necessary, and from the perspective of efficiency, the team can optimize the review process.

Question 5: With so many ADR templates, how should the team choose?

Answer:There is no standard, only the most suitable!

There is no unified ADR template; choose one suitable for the team. Suggestion:

Keep the template lightweight; do not try to cover all scenarios, otherwise, ADR will become a burden for team members.

More importantly, the meaning of the ADR template and its elements must be agreed upon among team members.

Question 6: When is it necessary to write ADR without quantitative conditions, making it difficult to implement?

Answer:No!

In principle: architectural decisions that have a significant impact on the system need to be written in an ADR.

How to define 'significant impact' does not have quantitative indicators, but if there are the following scenarios, it may be a signal for writing an ADR:

•Directly affect high-priority architectural attributes

•Modify the external interfaces: modifications to the interfaces provided externally often require sufficient impact analysis

•Introduce or remove dependencies: the addition and removal of dependencies often indicate the introduction and abandonment of component capabilities

•Change the general structure of the system: engineering structure is one of the important dimensions of application architecture

•Compel R&D personnel to change the development method and accept strategic technical debt: the refactoring of technical debt with a significant impact often has a significant impact on the existing system

The above scenarios are just some signals that may require writing an ADR, but not a mandatory agreement.

The ultimate practice criterion for whether to write an ADR is: specific situation, specific analysis

6 Common Misconceptions in ADR Writing

Although the structure of ADR is very simple, the team is prone to deviation in the expression of the content of each chapter when starting the practice process, and common problems when writing ADR documents are as follows:

【Background】section

Typical antonym:

Not directly stating the reason for promoting the decision: the correct way is to clearly state the background or motivation for this architectural decision, and clearly explain WHY; in the early stage of ADR practice, a common mistake made by the team is to have a detailed and lengthy discussion of the options in the 'Background' section

【Decision】section

Typical antonym:

Lack of decision basis description: the decision basis is too simple and insufficient, cannot lead to the arguments for choosing the current decision; the wording of the decision result is not clear, ambiguous

【Optional Solutions】section

Typical antonym: the analysis angle has obvious bias, not objective

【Consistency】section

The purpose of this chapter isPromote the architect to think deeply about how to ensure that the decision is followed by the team, especially considering whether it can be automated. Typical antonym vocabulary is: system landing, development implementation......

If it is not possible to check in different automated ways, possible ways may include design review, peer code review, and expert code review. If it is possible to automate, it should be explained how to automate the constraint verification. For example, if the engineering practice passes the unit test through Archunit, it can be expressed as rule code based on Archunit.