Architecture Decision Records in Practice: An Action Research Study

Paper i proceeding, 2024

To establish good architectural practice and knowledge sharing during software development and maintenance, architectural design decisions need to be documented. While a lot of research has been done on documenting architectural decisions, there exist few approaches with empirical evidence on their applicability and usefulness in practice. Architecture Decision Records are a popular documentation approach in industry, but there is a lack of research focusing on how Architecture Decision Records can be introduced in different company contexts. To tackle this shortcoming, we performed an action research study in cooperation with a company that develops a microservice-based system without proper architecture design decision documentation. We performed seven interviews to identify the challenges faced by the developers of the system. Afterward, we introduced Architecture Decision Records as a means of documentation. Over the course of three months, we observed whether this markdown-based documentation approach addresses the identified challenges. Our results show that practitioners face challenges related to the documentation culture, knowledge transfer, prioritization of information to be documented, as well as handling documentation for shared and distributed components. The first three types of challenges are well addressed by Architecture Decision Records. However, challenges arising from developing distributed systems remain open. Thus, there is a need for further research that helps to document design decisions for distributed systems effectively. We also compiled a list of lessons learned from our study. We found that cooperation among the teams was improved after the introduction of Architecture Decision Records. At the same time, the decision on where documentation is stored has a massive influence on its perceived usefulness. Practitioners should carefully consider what information to store centrally and what information to store in local repositories.