One Size Fits All? An Empirical Comparison of ADR Templates regarding Comprehension, Usability, and Ease of Adoption

2026-04-29

AI Summary

Existing Architecture Decision Record (ADR) templates lack empirical comparison regarding understandability, usability, and adoption difficulty, leaving practitioners without evidence-based guidance for selection. This study addresses this gap by integrating the DESMET FA evaluation framework with a controlled user experiment to systematically compare five prominent ADR templates—Tyree/Akerman, Nygard, arc42, Y-statements, and MADR—and further investigates Nygard and MADR through quantitative and qualitative feedback from undergraduate developers. Results indicate that Nygard achieves higher overall ratings, supporting concise and objective documentation, whereas MADR better facilitates the expression of structural details. The findings reveal a fundamental trade-off between conciseness and structure in ADR design and provide the first evidence-based selection guideline to help teams choose ADR templates aligned with their specific needs.

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 preliminary screening 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.

Problem

• Architectural Decision Records
• ADR templates
• comprehension
• usability
• ease of adoption

Innovation

• Architectural Decision Records
• Empirical Evaluation
• DESMET FA
• Template Comparison
• Software Architecture Documentation