One Size Fits All? An Empirical Comparison of ADR Templates regarding Comprehension, Usability, and Ease of Adoption CCS: Software and its engineering Software architectures CCS: Software and its engineering Documentation CCS: General and reference Empirical studies

Fernando Nogueira, Nabson Silva, Tayana Conte · 2026

Read One Size Fits All? An Empirical Comparison of ADR Templates regarding Comprehension, Usability, and Ease of Adoption CCS: Software and its engineering Software architectures CCS: Software and its engineering Documentation CCS: General and reference Empirical studies by Fernando Nogueira, Nabson Silva, Tayana Conte (2026) in the Tower of Babel, a free online library of public-domain works preserved in clean, searchable text. No sign-up. The full text is served as a plain-text file at a predictable URL, where text is present: https://antarctic-labs.com/tower-of-babel/arxiv-2604-27333.txt.

Introduction

Nogueira, Silva, and Conte compare five Architectural Decision Record templates on grasp, ease of use, and uptake. Documenting design decisions is key for system upkeep, newcomer training, and preventing knowledge loss. Yet few prior studies compared the templates. The five are Tyree and Akerman's template, Nygard's ADR, arc42, Y-statements, and MADR. Using the DESMET FA method in a two-step testing process, the two primary authors first evaluated all five from software architecture know-how. Then the top leaders advanced to further testing.

Catalog record

CREATORFernando Nogueira, Nabson Silva, Tayana Conte
YEAR2026
COLLECTIONPAPERS
FORMATTXT
FILE SIZE50694
LICENSEhttp://creativecommons.org/licenses/by/4.0/
RIGHTSCC BY
SOURCEarXiv

Source: https://arxiv.org/abs/2604.27333

Browse the full library · About the Tower of Babel

Full text

The opening of the work, from the library's hosted text:

One Size Fits All? An Empirical Comparison of ADR Templates regarding Comprehension, Usability, and Ease of Adoption CCS: Software and its engineering Software architectures CCS: Software and its engineering Documentation CCS: General and reference Empirical studies Fernando Nogueira, Nabson Silva, Tayana Conte Abstract . Context : Documenting Architectural Design Decisions (ADDs) is a critical factor in the software lifecycle, essential for efficient system maintenance, developer onboarding, and preventing knowledge vaporization. Although various templates for Architectural Decision Records (ADRs) have been proposed, there is a lack of empirical evidence comparing them. Goal : To address this gap, this paper aims to identify which ADR template best supports comprehension, usability, and ease of adoption: Tyree/Akerman’s template, Nygard’s ADR, arc42, Y-statements, and MADR. Method : We compared these templates using the DESMET FA method in a two-step evaluation. First, the two primary authors evaluated the five templates through the DESMET FA, based on their software architecture expertise. The two top-performing templates were then used as treatments in a controlled experiment conducted with undergraduate students. Results : In the feature analysis by experts, the top-performing templates were those of Nygard and MADR. In the subsequent controlled experiment, Nygard’s template outperformed MADR in terms of the Overall Score. Qualitative analysis of participant feedback revealed the factors influencing template preference. The findings indicate that Nygard supports concise and objective documentation, while MADR facilitates structural details and specific architectural requirements. Conclusion : This paper provides an evidence-based strategy for ADR template adoption by offering a comparison between them. The findings present a decision-making guide that assists practitioners and researchers in selecting ADR templates aligned with project constraints, aiming to minimize documentation overhead and increase architectural knowledge retention. 1. Introduction Software architecture plays a pivotal role throughout the software development lifecycle ( 8 ; 12 ; 23 ) , directly affecting maintainability and contributing to the accumulation of technical debt ( 4 ) . These effects are particularly pronounced during the long-term evolution of software systems, where architectural decisions shape both system adaptability and sustainability ( 3 ; 29 ; 22 ) . Despite this relevance, software development practices have often emphasized architectural design activities while paying comparatively less attention to the systematic validation and documentation of architectural decisions ( 12 ) . This imbalance has tangible consequences: rigorous architecture documentation supports effective maintenance and long-term knowledge preservation ( 1 ; 33 ) , whereas insufficient documentation hampers developer onboarding and intensifies the challenges associated with evolving complex software systems ( 24 ) . The documentation of Architectural Design Decisions (ADDs) ( 6 ; 8 ) plays a central role in preserving architectural knowledge over time. Architectural decisions are typically made by weighing the trade-offs among available technical alternatives ( 13 ) , and documenting this rationale enables development teams to later understand why a system was designed in a particular way. Beyond supporting retrospective understanding, ADD documentation informs future architectural decision-making ( 2 ) , helping teams avoid repeating past mistakes and mitigating the loss of architectural knowledge—often referred to as knowledge vaporization ( 14 ; 7 ; 5 ) . Given the relevance of ADD documentation, several approaches and tools have been proposed and adopted in industrial settings ( 15 ; 30 ) to support the management of architectural decision knowledge. However, empirical evidence comparing these approaches remains limited, particularly regarding their adoption, comprehensibility, and usability. According to 14 , these characteristics constitute essential quality attributes of effective decision documentation and are critical to its sustained use in practice. The concept of Architectural Decision Records (ADRs) has gained traction in agile environments, leading to the proposal of multiple templates such as Tyree/Akerman ( 30 ) , Nygard’s ADR ( 25 ) , and MADR ( 18 ) . Despite their increasing adoption, the selection of an ADR template in industrial practice is often guided by ad hoc preferences, personal experience, or community conventions rather than systematic empirical evidence. This lack of evidence-based guidance hinders informed decision-making and increases the risk of miscommunication of architectural decisions to developers or stakeholders. Although prior work highlights the importance of comprehensibility, usability, and ease of adoption for effective decision documentation ( 14 ) , empirical comparisons of ADR templates along these dimensions remain scarce. This work compares ADR templates by applying the DESMET Feature Analysis (FA) method ( 16 ) in a two-step evaluation. First, we applied the DESMET FA to screen five prominent templates, namely Tyree/Akerman ( 30 ) , Nygard’s ADR ( 25 ) , arc42 ( 28 ) , Y-statements ( 36 ) , and MADR ( 18 ) , to identify those most suitable for agile contexts. We selected these templates based on their prevalence in the industry, as suggested by 37 . This feature analysis resulted in the selection of Nygard and MADR as the top-performing templates. Subsequently, we conducted a controlled experiment with 33 undergraduate software engineering students as participants to compare these two templates. At this stage, we utilized the DESMET FA to calculate an Overall Score based on empirical metrics that cover comprehension, usability, and ease of adoption. By analyzing these scores, we assess which structural aspects contribute to a more effective balance between documentation effort and consumption, providing evidence-based guidance to practitioners to minimize documentation overhead. Furthermore, we performed a qualitative analysis of participant feedback to uncover the factors that influence template preference. The contributions of this study assist practitioners and researchers in navigating the trade-offs of architectural documentation, providing: • An empirical comparison of widely used ADR templates through a standardized evaluation • Evidence-based insights into how specific ADR structures impact documentation overhead and practitioner adoption • Evidence-based recommendation to assist architects in the ADR adoption in agile environments 2. Background This section explores the fundamental principles of Architectural Knowledge (AK) , Architectural Decisions (ADs) , and Architectural Decision Records (ADRs) . It establishes the theoretical foundation for understanding the context and significance of the proposed work. 2.1. Architectural Knowledge Architectural Knowledge (AK) constitutes the comprehensive representation of the design logic, extending beyond static artifacts to include the design decisions, assumptions, context, and rationale driving the system’s evolution ( 21 ) . Traditional documentation focuses primarily on the resulting components and connectors, often neglecting the reasoning behind their selection ( 26 ) . This omission creates a gap where critical knowledge remains implicit, residing solely in the architects’ minds. The loss of this tacit information leads to knowledge vaporization , a concept first described by 14 as the loss of embedded architectural knowledge. That highlights the problems arising from the loss of AK, such as violations of design rules and constraints, the maintenance of obsolete design decisions, and limitations on the reusability of architectural artifacts. 2.2. Architectural Decisions Architectural Decisions (ADs) represent the core units of change in software architecture. 22 propose treating ADs as first-class entities, shifting the architectural paradigm from a component-centric view ( 20 ; 8 ) to a decision-centric one. An AD is not an isolated event but a structured entity possessing distinct attributes, including rationale, scope, state, cost, and associated risks. The ontology of ADs categorizes these decisions into distinct classes: • Existence decisions: Choices regarding the inclusion of structural elements or artifacts in the

Read the complete text