Exploring the Adoption and Effectiveness of Architecture Decision Records in Agile Software Development: An Action Research Study

Paper in proceeding, 2023

Software development companies have a need to document and communicate their software architecture decisions. While a lot of research has been done on software architecture decision documentation, there exist few established practices that are applied in industry. In recent years, a markdown-based approach called Architecture Decision Records (ADRs) has been proposed. There is little empirical evidence and research on how Architecture Decision Records are used in practice. This study applies an action research method to investigate the challenges in documenting architecture decisions and the use of ADRs in practice. We found challenges within the areas culture and organisation, tacit knowledge, documentation process and tools. We introduced ADRs at a company over the course of two months, and observed advantages and challenges of using them. We found that ADRs are perceived as useful by development teams. ADRs hold promise for enhancing documentation practices, facilitating decision-making, and promoting a documentation culture within software development teams. However, sustained efforts are necessary to drive the implementation, refine guidelines, and
provide ongoing support to fully leverage the benefits of ADRs and ensure their successful integration into team workflows. Practitioners raise concerns about documenting too much or too little, prioritization, placement, and maintaining documentation up-to-date.