Skip to main content
Springer Nature Link
Log in

A Taxonomy for Design Decisions in Software Architecture Documentation

  • Conference paper
  • First Online:
Software Architecture. ECSA 2022 Tracks and Workshops (ECSA 2022)

Part of the book series: Lecture Notes in Computer Science ((LNCS,volume 13928))

Included in the following conference series:

  • 756 Accesses

Abstract

A software system is the result of all design decisions that were made during development and maintenance. Documentation, such as software architecture documentation, captures a variety of different design decisions. Classifying the kinds of design decisions facilitates various downstream tasks by enabling more targeted analyses. In this paper, we propose a taxonomy for design decisions in software architecture documentation to primarily support consistency checking. Existing taxonomies about design decisions have different purposes and do not fit well because they are too coarse. We take an iterative approach, starting with an initial taxonomy based on literature and considerations regarding consistency checking. Then, we mine open-source repositories to extract 17 software architecture documentations that we use to refine the taxonomy. We evaluate the resulting taxonomy with regard to purpose, structure, and application. Additionally, we explore the automatic identification and classification of design decisions in software architecture documentation according to the taxonomy. We apply different machine learning techniques, such as Logistic Regression, Decision Trees, Random Forests, and BERT to the 17 software architecture documentations. The evaluation yields a \(F_1\)-score of up to 92.1% for identifying design decisions and a \(F_1\)-score of up to 55.2% for the classification of the kind of design decision.

This is a preview of subscription content, log in via an institution to check access.

Access this chapter

Log in via an institution

Subscribe and save

Springer+ Basic
$34.99 /Month
  • Get 10 units per month
  • Download Article/Chapter or eBook
  • 1 Unit = 1 Article or 1 Chapter
  • Cancel anytime
Subscribe now

Buy Now

Chapter
USD 29.95
Price excludes VAT (USA)
  • Available as PDF
  • Read on any device
  • Instant download
  • Own it forever

Tax calculation will be finalised at checkout

Purchases are for personal use only

Institutional subscriptions

References

  1. ISO/IEC/IEEE Systems and software engineering - Architecture description. ISO/IEC/IEEE 42010:2011(E) (2011). https://doi.org/10.1109/IEEESTD.2011.6129467

  2. ANSI/NISO: Guidelines for the Construction, Format, and Management of Monolingual Controlled Vocabularies. Standard, NISO (2005). https://www.niso.org/publications/ansiniso-z3919-2005-r2010

  3. Bedford, D.: Evaluating classification schema and classification decisions. Bull. Am. Soc. Inf. Sci. Technol. 39(2), 13–21 (2013). https://doi.org/10.1002/bult.2013.1720390206

    Article  MathSciNet  Google Scholar 

  4. Bhat, M., Shumaiev, K., Biesdorf, A., Hohenstein, U., Matthes, F.: Automatic extraction of design decisions from issue management systems: a machine learning based approach. In: Lopes, A., de Lemos, R. (eds.) ECSA 2017. LNCS, vol. 10475, pp. 138–154. Springer, Cham (2017). https://doi.org/10.1007/978-3-319-65831-5_10

    Chapter  Google Scholar 

  5. Cook, S., et al.: Unified modeling language (UML) version 2.5.1. Standard, Object Management Group (OMG) (2017). https://www.omg.org/spec/UML/2.5.1

  6. Devlin, J., Chang, M.W., Lee, K., Toutanova, K.: BERT: pre-training of deep bidirectional transformers for language understanding. In: Proceedings of the 2019 NAACL, pp. 4171–4186. ACL (2019). https://doi.org/10.18653/v1/N19-1423

  7. Falessi, D., Becker, M., Cantone, G.: Design decision rationale: experiences and steps ahead towards systematic use. SIGSOFT Softw. Eng. Notes 31(5), 2-es (2006). https://doi.org/10.1145/1163514.1178642

  8. Fu, L., Liang, P., Li, X., Yang, C.: A machine learning based ensemble method for automatic multiclass classification of decisions. In: Evaluation and Assessment in Software Engineering, EASE 2021, pp. 40–49. Association for Computing Machinery, New York (2021). https://doi.org/10.1145/3463274.3463325

  9. Golden, B.: A unified formalism for complex systems architecture. Ph.D. thesis, Ecole Polytechnique X (2013)

    Google Scholar 

  10. Hey, T., Keim, J., Koziolek, A., Tichy, W.F.: NoRBERT: transfer learning for requirements classification. In: IEEE 28th RE, pp. 169–179 (2020). https://doi.org/10.1007/978-3-319-65831-5_10

  11. Hoare, C.A.R.: Communicating sequential processes. Commun. ACM 21(8), 666–677 (1978). https://doi.org/10.1145/359576.359585

    Article  MATH  Google Scholar 

  12. Jansen, A., Bosch, J.: Software architecture as a set of architectural design decisions. In: 5th Working IEEE/IFIP Conference on Software Architecture (WICSA 2005), pp. 109–120 (2005). https://doi.org/10.1109/WICSA.2005.61

  13. Kaplan, A., et al.: Introducing an evaluation method for taxonomies. In: EASE 2022: Evaluation and Assessment in Software Engineering. ACM (2022)

    Google Scholar 

  14. Keim, J., Hey, T., Sauer, B., Koziolek, A.: Supplementary Material of “A Taxonomy for Design Decisions in Software Architecture Documentation” (2022). https://doi.org/10.5281/zenodo.6956851

  15. Keim, J., Koziolek, A.: Towards consistency checking between software architecture and informal documentation. In: 2019 ICSA, pp. 250–253 (2019)

    Google Scholar 

  16. Krippendorff, K.: Reliability in content analysis: some common misconceptions and recommendations. Hum. Commun. Res. 30(3), 411–433 (2004)

    Google Scholar 

  17. Krippendorff, K.: Content Analysis: An Introduction to Its Methodology. SAGE Publications, Thousand Oaks (2018)

    Google Scholar 

  18. Kruchten, P.: An ontology of architectural design decisions in software-intensive systems. In: 2nd Groningen Workshop on Software Variability, pp. 54–61 (2004)

    Google Scholar 

  19. Li, X., Liang, P., Li, Z.: Automatic identification of decisions from the hibernate developer mailing list. In: Proceedings of EASE 2020, pp. 51–60. ACM (2020)

    Google Scholar 

  20. Lytra, I., Zdun, U.: Inconsistency management between architectural decisions and designs using constraints and model fixes. In: 23rd Australian Software Engineering Conference (2014). https://doi.org/10.1109/ASWEC.2014.33

  21. Miesbauer, C., Weinreich, R.: Classification of design decisions – an expert survey in practice. In: Drira, K. (ed.) ECSA 2013. LNCS, vol. 7957, pp. 130–145. Springer, Heidelberg (2013). https://doi.org/10.1007/978-3-642-39031-9_12

    Chapter  Google Scholar 

  22. Parnas, D.L.: Precise documentation: the key to better software. In: Nanz, S. (ed.) The Future of Software Engineering, pp. 125–148. Springer, Heidelberg (2011). https://doi.org/10.1007/978-3-642-15187-3_8

    Chapter  Google Scholar 

  23. Ralph, P.: Toward methodological guidelines for process theories and taxonomies in software engineering. IEEE Trans. Software Eng. 45(7), 712–735 (2019). https://doi.org/10.1109/TSE.2018.2796554

    Article  Google Scholar 

  24. Reussner, R.H., Becker, S., Happe, J., Heinrich, R., Koziolek, A.: Modeling and Simulating Software Architectures: The Palladio Approach. MIT Press, Cambridge (2016)

    Google Scholar 

  25. Runeson, P., Höst, M.: Guidelines for conducting and reporting case study research in software engineering. Empir. Software Eng. 14(2), 131 (2008)

    Article  Google Scholar 

  26. Shahin, M., Liang, P., Khayyambashi, M.R.: Architectural design decision: Existing models and tools. In: 2009 Joint WICSA & ECSA, pp. 293–296 (2009)

    Google Scholar 

  27. Sullivan, K.J., Griswold, W.G., Cai, Y., Hallen, B.: The structure and value of modularity in software design. SIGSOFT SE Notes 26(5), 99–108 (2001)

    Article  Google Scholar 

  28. Szyperski, C., Gruntz, D., Murer, S.: Component Software: Beyond Object-Oriented Programming. Pearson Education, London (2002)

    Google Scholar 

  29. Vegas, S., Juristo, N., Basili, V.R.: Maturing software engineering knowledge through classifications: a case study on unit testing techniques. IEEE Trans. Softw. Eng. 35(4), 551–565 (2009). https://doi.org/10.1109/TSE.2009.13

    Article  Google Scholar 

  30. Wohlrab, R., Eliasson, U., Pelliccione, P., Heldal, R.: Improving the consistency and usefulness of architecture descriptions: guidelines for architects. In: 2019 ICSA, pp. 151–160 (2019). https://doi.org/10.1109/ICSA.2019.00024

  31. Zimmermann, O., Gschwind, T., Küster, J., Leymann, F., Schuster, N.: Reusable architectural decision models for enterprise application development. In: Overhage, S., Szyperski, C.A., Reussner, R., Stafford, J.A. (eds.) QoSA 2007. LNCS, vol. 4880, pp. 15–32. Springer, Heidelberg (2007). https://doi.org/10.1007/978-3-540-77619-2_2

    Chapter  Google Scholar 

Download references

Author information

Authors and Affiliations

  1. KASTEL - Institute of Information Security and Dependability, Karlsruhe Institute of Technology (KIT), Karlsruhe, Germany

    Jan Keim, Tobias Hey, Bjarne Sauer & Anne Koziolek

Authors
  1. Jan Keim
    View author publications

    You can also search for this author in PubMed Google Scholar

  2. Tobias Hey
    View author publications

    You can also search for this author in PubMed Google Scholar

  3. Bjarne Sauer
    View author publications

    You can also search for this author in PubMed Google Scholar

  4. Anne Koziolek
    View author publications

    You can also search for this author in PubMed Google Scholar

Corresponding author

Correspondence to Jan Keim .

Editor information

Editors and Affiliations

  1. Federal University of Rio Grande do Norte, Natal, Brazil

    Thais Batista

  2. Charles University, Prague, Czech Republic

    Tomáš Bureš

  3. Vrije Universiteit Amsterdam, Amsterdam, The Netherlands

    Claudia Raibulet

  4. University of L’Aquila, L’Aquila, Italy

    Henry Muccini

Rights and permissions

Reprints and permissions

Copyright information

© 2023 The Author(s), under exclusive license to Springer Nature Switzerland AG

About this paper

Check for updates. Verify currency and authenticity via CrossMark

Cite this paper

Keim, J., Hey, T., Sauer, B., Koziolek, A. (2023). A Taxonomy for Design Decisions in Software Architecture Documentation. In: Batista, T., Bureš, T., Raibulet, C., Muccini, H. (eds) Software Architecture. ECSA 2022 Tracks and Workshops. ECSA 2022. Lecture Notes in Computer Science, vol 13928. Springer, Cham. https://doi.org/10.1007/978-3-031-36889-9_29

Download citation

  • DOI: https://doi.org/10.1007/978-3-031-36889-9_29

  • Published:

  • Publisher Name: Springer, Cham

  • Print ISBN: 978-3-031-36888-2

  • Online ISBN: 978-3-031-36889-9

  • eBook Packages: Computer ScienceComputer Science (R0)

Publish with us

Policies and ethics