Abstract
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.
This is a preview of subscription content, log in via an institution to check access.
Access this chapter
Tax calculation will be finalised at checkout
Purchases are for personal use only
Similar content being viewed by others
Data Availability Statement
We published our study material consisting of two questionnaires, our interview guides, and information on the codes used during our analysis at [1]. We cannot publish the collected raw data due to confidentiality.
References
Ahmeti, B., Linder, M., Groner, R., Wohlrab, R.: Supplementary material (2024). https://doi.org/10.5281/zenodo.11635100
Alexeeva, Z., Perez-Palacin, D., Mirandola, R.: Design decision documentation: a literature overview. In: Tekinerdogan, B., Zdun, U., Babar, A. (eds.) ECSA 2016. LNCS, vol. 9839, pp. 84–101. Springer, Cham (2016). https://doi.org/10.1007/978-3-319-48992-6_6
Buchgeher, G., Schöberl, S., Geist, V., Dorninger, B., Haindl, P., Weinreich, R.: Using architecture decision records in open source projects-an MSR study on GitHub. IEEE Access 11, 63725–63740 (2023). https://doi.org/10.1109/ACCESS.2023.3287654
Capilla, R., Nava, F., Montes, J., Carrillo, C., et al.: ADDSS: architecture design decision support system tool (2010)
Clark, V.L.P., Ivankova, N.V.: Mixed Methods Research: A Guide to the Field, vol. 3. Sage Publications, Thousand Oaks (2015)
Dasanayake, S., Markkula, J., Aaramaa, S., Oivo, M.: Software architecture decision-making practices and challenges: an industrial case study. In: Proceedings of the 2015 24th Australasian Software Engineering Conference, pp. 88–97 (2015). https://doi.org/10.1109/ASWEC.2015.20
Ernst, N.A., Robillard, M.P.: A study of documentation for software architecture. Empir. Softw. Eng. 28(5), 122 (2023)
Forward, A., Lethbridge, T.C.: The relevance of software documentation, tools and technologies: a survey. In: Proceedings of the 2002 ACM Symposium on Document Engineering, pp. 26–33. DocEng ’02, Association for Computing Machinery, New York, NY, USA (2002). https://doi.org/10.1145/585058.585065
Haselböck, S., Weinreich, R., Buchgeher, G.: Decision models for microservices: design areas, stakeholders, use cases, and requirements. In: Lopes, A., de Lemos, R. (eds.) ECSA 2017. LNCS, vol. 10475, pp. 155–170. Springer, Cham (2017). https://doi.org/10.1007/978-3-319-65831-5_11
Keeling, M.: The psychology of architecture decision records. IEEE Softw. 39(6), 114–117 (2022). https://doi.org/10.1109/MS.2022.3198195
Kleehaus, M., Matthes, F.: Challenges in documenting microservice-based it landscape: a survey from an enterprise architecture management perspective. In: Proceedings of the 2019 IEEE 23rd International Enterprise Distributed Object Computing Conference (EDOC), pp. 11–20 (2019).https://doi.org/10.1109/EDOC.2019.00012
Kopp, O., Armbruster, A., Zimmermann, O.: Markdown architectural decision records: format and tool support. In: ZEUS, pp. 55–62 (2018)
Lee, L., Kruchten, P.: A tool to visualize architectural design decisions. In: Becker, S., Plasil, F., Reussner, R. (eds.) QoSA 2008. LNCS, vol. 5281, pp. 43–54. Springer, Heidelberg (2008). https://doi.org/10.1007/978-3-540-87879-7_3
Liang, P., Jansen, A., Avgeriou, P.: Knowledge Architect: A Tool Suite for Managing Software Architecture Knowledge. University of Groningen, Johann Bernoulli Institute for Mathematics and Computer Science (2009). relation: http://www.rug.nl/informatica/organisatie/overorganisatie/iwi Rights: University of Groningen, Research Institute for Mathematics and Computing Science (IWI)
Manteuffel, C., Avgeriou, P., Hamberg, R.: An exploratory case study on reusing architecture decisions in software-intensive system projects. J. Syst. Softw. 144, 60–83 (2018). https://doi.org/10.1016/j.jss.2018.05.064
Manteuffel, C., Tofan, D., Koziolek, H., Goldschmidt, T., Avgeriou, P.: Industrial implementation of a documentation framework for architectural decisions. In: Proceedings of the 2014 IEEE/IFIP Conference on Software Architecture, pp. 225–234. IEEE (2014)
Nygard, M.: Documenting architecture decisions (2011). https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions. Accessed 12 Apr 2024
Rost, D., Naab, M., Lima, C., von Flach Garcia Chavez, C.: Software architecture documentation for developers: a survey. In: Drira, K. (ed.) ECSA 2013. LNCS, vol. 7957, pp. 72–88. Springer, Heidelberg (2013). https://doi.org/10.1007/978-3-642-39031-9_7
Saldaña, J.: The coding manual for qualitative researchers (2013)
Shahin, M., Liang, P., Khayyambashi, M.R.: Architectural design decision: existing models and tools. In: Proceedings of the 2009 Joint Working IEEE/IFIP Conference on Software Architecture & European Conference on Software Architecture, pp. 293–296 (2009). https://doi.org/10.1109/WICSA.2009.5290823
Staron, M.: Action Research in Software Engineering. Springer, Berlin, Heidelberg (2020). https://doi.org/10.1007/978-3-030-32610-4
Tyree, J., Akerman, A.: Architecture decisions: demystifying architecture. IEEE Softw. 22(2), 19–27 (2005). https://doi.org/10.1109/MS.2005.27
van Heesch, U., Avgeriou, P., Hilliard, R.: A documentation framework for architecture decisions. J. Syst. Softw. 85(4), 795–820 (2012). https://doi.org/10.1016/j.jss.2011.10.017
Acknowledgments
This work was partially supported by the Wallenberg AI, Autonomous Systems and Software Program (WASP) funded by the Knut and Alice Wallenberg Foundation.
Author information
Authors and Affiliations
Corresponding author
Editor information
Editors and Affiliations
Rights and permissions
Copyright information
© 2024 The Author(s), under exclusive license to Springer Nature Switzerland AG
About this paper
Cite this paper
Ahmeti, B., Linder, M., Groner, R., Wohlrab, R. (2024). Architecture Decision Records in Practice: An Action Research Study. In: Galster, M., Scandurra, P., Mikkonen, T., Oliveira Antonino, P., Nakagawa, E.Y., Navarro, E. (eds) Software Architecture. ECSA 2024. Lecture Notes in Computer Science, vol 14889. Springer, Cham. https://doi.org/10.1007/978-3-031-70797-1_22
Download citation
DOI: https://doi.org/10.1007/978-3-031-70797-1_22
Published:
Publisher Name: Springer, Cham
Print ISBN: 978-3-031-70796-4
Online ISBN: 978-3-031-70797-1
eBook Packages: Computer ScienceComputer Science (R0)