Skip to main content
SpringerLink
Log in

Design Decision Documentation: A Literature Overview

  • Conference paper
  • First Online:
Software Architecture (ECSA 2016)

Part of the book series: Lecture Notes in Computer Science ((LNPSE,volume 9839))

Included in the following conference series:

Abstract

Despite the abundance of research on methodologies for the documentation of design decisions and the evidence linking documentation to the improvement in the systems evolution, their practical adoption seems to be sparse. To understand this issue, we have conducted an overview of state-of-the-art on documentation of design decisions. We pursue an identification of characteristics of the different techniques proposed in the literature, such as the final goal of the documentation, the quantity of information attached to each decision documentation, the rigour of the proposed technique or its level of automation. To unveil these, we propose six classification dimensions, relevant for the industrial application, and use them to structure and analyse the review results. This work contributes with a taxonomy of the area, a structured overview covering 96 publications and a summary of open questions, which can be addressed by future research to facilitate practical adoption.

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

Access this chapter

Log in via an institution
Chapter
USD 29.95
Price excludes VAT (USA)
  • Available as PDF
  • Read on any device
  • Instant download
  • Own it forever
eBook
USD 39.99
Price excludes VAT (USA)
  • Available as EPUB and PDF
  • Read on any device
  • Instant download
  • Own it forever
Softcover Book
USD 54.99
Price excludes VAT (USA)
  • Compact, lightweight edition
  • Dispatched in 3 to 5 business days
  • Free shipping worldwide - see info

Tax calculation will be finalised at checkout

Purchases are for personal use only

Institutional subscriptions

References

  1. Ozkaya, I., Wallin, P., Axelsson, J.: Architecture knowledge management during system evolution: observations from practitioners. In: SHARK (2010)

    Google Scholar 

  2. Taylor, R.N., Medvidovic, N., Dashofy, E.M.: Software Architecture: Foundations, Theory, and Practice. Wiley, New York (2009)

    Book  Google Scholar 

  3. Kruchten, P., Capilla, R., Dueas, J.: The decision view’s role in software architecture practice. IEEE Softw. 26, 36–42 (2009)

    Article  Google Scholar 

  4. Burge, J.E., Carroll, J.M., McCall, R., Mistrik, I.: Rationale-Based Software Engineering. Springer, Heidelberg (2008)

    Book  MATH  Google Scholar 

  5. Tang, A., Babar, M.A., Gorton, I., Han, J.: A survey of architecture design rationale. J. Syst. Softw. 79, 1792–1804 (2006)

    Article  Google Scholar 

  6. Babar, M., Tang, A., Gorton, I., Han, J.: Industrial perspective on the usefulness of design rationale for software maintenance: a survey. In: 2006 6th International Conference on Quality Software (QSIC), pp. 201–208 (2006)

    Google Scholar 

  7. Manteuffel, C., Tofan, D., Koziolek, H., Goldschmidt, T., Avgeriou, P.: Industrial implementation of a documentation framework for architectural decisions. In: WICSA (2014)

    Google Scholar 

  8. Nkwocha, A., Hall, J.G., Rapanotti, L.: Design rationale capture for process improvement in the globalised enterprise: an industrial study. Softw. Syst. Model. 12, 825–845 (2013)

    Article  Google Scholar 

  9. Burge, J.E., Brown, D.C.: Software engineering using RATionale. J. Syst. Softw. 81, 395–413 (2008)

    Article  Google Scholar 

  10. Anvaari, M., Zimmermann, O.: Semi-automated Design Guidance Enhancer (SADGE): a framework for architectural guidance development. In: Avgeriou, P., Zdun, U. (eds.) ECSA 2014. LNCS, vol. 8627, pp. 41–49. Springer, Heidelberg (2014). doi:10.1007/978-3-319-09970-5_4

    Google Scholar 

  11. Dragomir, A., Lichter, H., Budau, T.: Systematic architectural decision management: a process-based approach. In: WICSA (2014)

    Google Scholar 

  12. Falessi, D., Briand, L.C., Cantone, G., Capilla, R., Kruchten, P.: The value of design rationale information. ACM Trans. Softw. Eng. Methodol. 22(3), 21 (2013)

    Article  Google Scholar 

  13. Tofan, D., Galster, M., Avgeriou, P.: Difficulty of architectural decisions – a survey with professional architects. In: Drira, K. (ed.) ECSA 2013. LNCS, vol. 7957, pp. 192–199. Springer, Heidelberg (2013). doi:10.1007/978-3-642-39031-9_17

    Chapter  Google Scholar 

  14. Tang, A., Avgeriou, P., Jansen, A., Capilla, R., Babar, M.A.: A comparative study of architecture knowledge management tools. J. Syst. Softw. 83, 352–370 (2010)

    Article  Google Scholar 

  15. Babar, M., de Boer, R., Dingsoyr, T., Farenhorst, R.: Architectural knowledge management strategies: approaches in research and industry. In: SHARK (2007)

    Google Scholar 

  16. Rozanski, N., Woods, E.: Software Systems Architecture: Working with Stakeholders Using Viewpoints and Perspectives. Addison-Wesley Professional, Upper Saddle River (2009)

    Google Scholar 

  17. Tyree, J., Akerman, A.: Architecture decisions: demystifying architecture. IEEE Softw. 22(2), 19–27 (2005)

    Article  Google Scholar 

  18. Jansen, A., Bosch, J.: Software architecture as a set of architectural design decisions. In: 5th Working IEEE/IFIP Conference on Software Architecture, WICSA (2005)

    Google Scholar 

  19. Kruchten, P.: An ontology of architectural design decisions in software intensive systems. In: 2nd Groningen Workshop on Software Variability (2004)

    Google Scholar 

  20. Regli, W., Hu, X., Atwood, M., Sun, W.: A survey of design rationale systems: approaches, representation, capture and retrieval. Eng. Comput. 16, 209–235 (2000)

    Article  MATH  Google Scholar 

  21. Shahin, M., Liang, P., Khayyambashi, M.: Architectural design decision: existing models and tools. In: WICSA/ECSA (2009)

    Google Scholar 

  22. Farenhorst, R., Lago, P., Vliet, H.: Effective tool support for architectural knowledge sharing. In: Oquendo, F. (ed.) ECSA 2007. LNCS, vol. 4758, pp. 123–138. Springer, Heidelberg (2007). doi:10.1007/978-3-540-75132-8_11

    Chapter  Google Scholar 

  23. Bu, W., Tang, A., Han, J.: An analysis of decision-centric architectural design approaches. In: SHARK (2009)

    Google Scholar 

  24. Henttonen, K., Matinlassi, M.: Open source based tools for sharing and reuse of software architectural knowledge. In: WICSA/ECSA (2009)

    Google Scholar 

  25. Hoorn, J.F., Farenhorst, R., Lago, P., van Vliet, H.: The lonesome architect. J. Syst. Softw. 84(9), 1424–1435 (2011)

    Article  Google Scholar 

  26. Kitchenham, B.: Procedures for performing systematic reviews. Keele University Technical report TR/SE-0401 and NICTA Technical report 0400011T.1 (2004)

    Google Scholar 

  27. de Boer, R.C., Farenhorst, R.: In search of ‘architectural knowledge’. In: SHARK (2008)

    Google Scholar 

  28. Koziolek, H.: Performance evaluation of component-based software systems: a survey. Perform. Eval. 67, 634–658 (2010)

    Article  Google Scholar 

  29. Aleti, A., Buhnova, B., Grunske, L., Koziolek, A., Meedeniya, I.: Software architecture optimization methods: a systematic literature review. IEEE Trans. Softw. Eng. 39, 658–683 (2013)

    Article  Google Scholar 

  30. University of Illinois: Software Engineering Conferences (2014)

    Google Scholar 

  31. IEEE: IEEE Digital Library. http://ieeexplore.ieee.org/search/advsearch.jsp

  32. DBLP: Search DBLP Computer Science Bibliography. http://dblp.uni-trier.de/search/

  33. ACM: ACM Digital Library. http://dl.acm.org/advsearch.cfm

  34. Zimmermann, O., Wegmann, L., Koziolek, H., Goldschmidt, T.: Architectural decision guidance across projects - problem space modeling, decision backlog management and cloud computing knowledge. In: WICSA (2015)

    Google Scholar 

  35. Capilla, R., Zimmermann, O., Zdun, U., Avgeriou, P., Küster, J.M.: An enhanced architectural knowledge metamodel linking architectural design decisions to other artifacts in the software engineering lifecycle. In: Crnkovic, I., Gruhn, V., Book, M. (eds.) ECSA 2011. LNCS, vol. 6903, pp. 303–318. Springer, Heidelberg (2011). doi:10.1007/978-3-642-23798-0_33

    Chapter  Google Scholar 

  36. Eloranta, V.P., Hylli, O., Vepsalainen, T., Koskimies, K.: TopDocs: using software architecture knowledge base for generating topical documents. In: WICSA/ECSA (2012)

    Google Scholar 

  37. Könemann, P., Zimmermann, O.: Linking design decisions to design models in model-based software development. In: Babar, M.A., Gorton, I. (eds.) ECSA 2010. LNCS, vol. 6285, pp. 246–262. Springer, Heidelberg (2010). doi:10.1007/978-3-642-15114-9_19

    Chapter  Google Scholar 

  38. Buchgeher, G., Weinreich, R.: Automatic tracing of decisions to architecture and implementation. In: WICSA (2011)

    Google Scholar 

  39. Durdik, Z., Reussner, R.: On the appropriate rationale for using design patterns and pattern documentation. In: QoSA (2013)

    Google Scholar 

  40. Jansen, A., van der Ven, J., Avgeriou, P., Hammer, D.K.: Tool support for architectural decisions. In: WICSA (2007)

    Google Scholar 

  41. Küster, M.: Architecture-centric modeling of design decisions for validation and traceability. In: Drira, K. (ed.) ECSA 2013. LNCS, vol. 7957, pp. 184–191. Springer, Heidelberg (2013). doi:10.1007/978-3-642-39031-9_16

    Chapter  Google Scholar 

  42. Navarro, E., Cuesta, C., Perry, D.: Weaving a network of architectural knowledge. In: WICSA/ECSA (2009)

    Google Scholar 

  43. Zimmermann, O., Miksovic, C., KüSter, J.M.: Reference architecture, metamodel, and modeling principles for architectural knowledge management in information technology services. J. Syst. Softw. 85, 2014–2033 (2012)

    Article  Google Scholar 

  44. Boer, R.C., Farenhorst, R., Lago, P., Vliet, H., Clerc, V., Jansen, A.: Architectural knowledge: getting to the core. In: Overhage, S., Szyperski, C.A., Reussner, R., Stafford, J.A. (eds.) QoSA 2007. LNCS, vol. 4880, pp. 197–214. Springer, Heidelberg (2007). doi:10.1007/978-3-540-77619-2_12

    Chapter  Google Scholar 

  45. Miller, J.A., Ferrari, R., Madhavji, N.H.: An exploratory study of architectural effects on requirements decisions. J. Syst. Softw. 83, 2441–2455 (2010)

    Article  Google Scholar 

  46. Shahin, M., Liang, P., Khayyambashi, M.R.: Improving understandability of architecture design through visualization of architectural design decision. In: SHARK (2010)

    Google Scholar 

  47. That, M.T.T., Sadou, S., Oquendo, F.: Using architectural patterns to define architectural decisions. In: WICSA/ECSA (2012)

    Google Scholar 

  48. Zimmermann, O., Koehler, J., Leymann, F., Polley, R., Schuster, N.: Managing architectural decision models with dependency relations, integrity constraints, and production rules. J. Syst. Softw. 82, 1249–1267 (2009)

    Article  Google Scholar 

  49. Cui, X., Sun, Y., Mei, H.: Towards automated solution synthesis and rationale capture in decision-centric architecture design. In: WICSA (2008)

    Google Scholar 

  50. Miesbauer, C., Weinreich, R.: WICSA/ECSA (2012)

    Google Scholar 

  51. Mirakhorli, M., Cleland-Huang, J.: Transforming trace information in architectural documents into re-usable and effective traceability links. In: SHARK (2011)

    Google Scholar 

  52. van Heesch, U., Avgeriou, P., Tang, A.: Does decision documentation help junior designers rationalize their decisions? A comparative multiple-case study. J. Syst. Softw. 86(6), 1545–1565 (2013)

    Article  Google Scholar 

  53. Szlenk, M., Zalewski, A., Kijas, S.: Modelling architectural decisions under changing requirements. In: WICSA/ECSA (2012)

    Google Scholar 

  54. Nowak, M., Pautasso, C.: Goals, questions and metrics for architectural decision models. In: SHARK (2011)

    Google Scholar 

  55. Eklund, U., Arts, T.: A classification of value for software architecture decisions. In: Babar, M.A., Gorton, I. (eds.) ECSA 2010. LNCS, vol. 6285, pp. 368–375. Springer, Heidelberg (2010). doi:10.1007/978-3-642-15114-9_30

    Chapter  Google Scholar 

  56. Tang, A., Jin, Y., Han, J.: A rationale-based architecture model for design traceability and reasoning. J. Syst. Softw. 80, 918–934 (2007)

    Article  Google Scholar 

  57. Capilla, R., Ali Babar, M.: On the role of architectural design decisions in software product line engineering. In: Morrison, R., Balasubramaniam, D., Falkner, K. (eds.) ECSA 2008. LNCS, vol. 5292, pp. 241–255. Springer, Heidelberg (2008). doi:10.1007/978-3-540-88030-1_18

    Chapter  Google Scholar 

  58. Bortis, G.: Informal software design knowledge reuse. In: ICSE (2010)

    Google Scholar 

  59. Savolainen, J., Kuusela, J., Männistö, T., Nyyssönen, A.: Experiences in making architectural decisions during the development of a new base station platform. In: Ali Babar, M., Gorton, I. (eds.) ECSA 2010. LNCS, vol. 6285, pp. 425–432. Springer, Heidelberg (2010). doi:10.1007/978-3-642-15114-9_37

    Chapter  Google Scholar 

  60. Miksovic, C., Zimmermann, O.: Architecturally significant requirements, reference architecture, and metamodel for knowledge management in information technology services. In: WICSA (2011)

    Google Scholar 

  61. Lago, P., Avgeriou, P., Capilla, R., Kruchten, P.: Wishes and boundaries for a software architecture knowledge community. In: WICSA (2008)

    Google Scholar 

  62. Komiya, S.: A model for the recording and reuse of software design decisions and decision rationale. In: Software Reuse: Advances in Software Reusability (1994)

    Google Scholar 

  63. Babar, M.A., Gorton, I.: A tool for managing software architecture knowledge. In: SHARK (2007)

    Google Scholar 

  64. de Boer, R., Van Vliet, H.: Experiences with semantic wikis for architectural knowledge management. In: WICSA (2011)

    Google Scholar 

  65. Wang, W., Burge, J.E.: Using rationale to support pattern-based architectural design. In: SHARK (2010)

    Google Scholar 

  66. Capilla, R., Dueñas, J.C., Nava, F.: Viability for codifying and documenting architectural design decisions with tool support. J. Softw. Maint. Evol. 22, 81–119 (2010)

    Article  Google Scholar 

  67. Carignano, M., Gonnet, S., Leone, H.: A model to represent architectural design rationale. In: WICSA/ECSA (2009)

    Google Scholar 

  68. Che, M.: An approach to documenting and evolving architectural design decisions. In: Proceedings of the 2013 International Conference on Software Engineering, ICSE (2013)

    Google Scholar 

  69. de Silva, L., Balasubramaniam, D.: A model for specifying rationale using an architecture description language. In: Crnkovic, I., Gruhn, V., Book, M. (eds.) ECSA 2011. LNCS, vol. 6903, pp. 319–327. Springer, Heidelberg (2011). doi:10.1007/978-3-642-23798-0_34

    Chapter  Google Scholar 

  70. Díaz, J., Pérez, J., Garbajosa, J., Wolf, A.L.: Change impact analysis in product-line architectures. In: Crnkovic, I., Gruhn, V., Book, M. (eds.) ECSA 2011. LNCS, vol. 6903, pp. 114–129. Springer, Heidelberg (2011). doi:10.1007/978-3-642-23798-0_12

    Chapter  Google Scholar 

  71. Egyed, A., Wile, D.: Support for managing design-time decisions. IEEE Trans. Softw. Eng. 32, 299–314 (2006)

    Article  Google Scholar 

  72. Garcia, A., Batista, T., Rashid, A., Sant’Anna, C.: Driving and managing architectural decisions with aspects. SIGSOFT Softw. Eng. Notes 31, 6 (2006)

    Article  Google Scholar 

  73. Gerdes, S., Lehnert, S., Riebisch, M.: Combining architectural design decisions and legacy system evolution. In: Avgeriou, P., Zdun, U. (eds.) ECSA 2014. LNCS, vol. 8627, pp. 50–57. Springer, Heidelberg (2014). doi:10.1007/978-3-319-09970-5_5

    Google Scholar 

  74. Gu, Q., Lago, P.: SOA process decisions: new challenges in architectural knowledge modeling. In: SHARK (2008)

    Google Scholar 

  75. Gu, Q., van Vliet, H.: SOA decision making - what do we need to know. In: SHARK (2009)

    Google Scholar 

  76. Habli, I., Kelly, T.: Capturing and replaying architectural knowledge through derivational analogy. In: SHARK (2007)

    Google Scholar 

  77. Harrison, N.B., Avgeriou, P., Zdun, U.: Using patterns to capture architectural decisions. IEEE Softw. 24, 38–45 (2007)

    Article  Google Scholar 

  78. Jansen, A., Bosch, J., Avgeriou, P.: Documenting after the fact: recovering architectural design decisions. J. Syst. Softw. 81, 536–557 (2008)

    Article  Google Scholar 

  79. Jansen, A., Avgeriou, P., van der Ven, J.S.: Enriching software architecture documentation. J. Syst. Softw. 82, 1232–1248 (2009)

    Article  Google Scholar 

  80. 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). doi:10.1007/978-3-540-87879-7_3

    Chapter  Google Scholar 

  81. Lytra, I., Tran, H., Zdun, U.: Supporting consistency between architectural design decisions and component models through reusable architectural knowledge transformations. In: Drira, K. (ed.) ECSA 2013. LNCS, vol. 7957, pp. 224–239. Springer, Heidelberg (2013). doi:10.1007/978-3-642-39031-9_20

    Chapter  Google Scholar 

  82. Cuesta, C.E., Navarro, E., Perry, D.E., Roda, C.: Evolution styles: using architectural knowledge as an evolution driver. J. Softw. Evol. Process 25(9), 957–980 (2013)

    Article  Google Scholar 

  83. Sinnema, M., van der Ven, J.S., Deelstra, S.: Using variability modeling principles to capture architectural knowledge. SIGSOFT Softw. Eng. Notes 31, 5 (2006)

    Google Scholar 

  84. Soliman, M., Riebisch, M., Zdun, U.: Enriching architecture knowledge with technology design decisions. In: WICSA (2015)

    Google Scholar 

  85. Tibermacine, C., Zernadji, T.: Supervising the evolution of web service orchestrations using quality requirements. In: Crnkovic, I., Gruhn, V., Book, M. (eds.) ECSA 2011. LNCS, vol. 6903, pp. 1–16. Springer, Heidelberg (2011). doi:10.1007/978-3-642-23798-0_1

    Chapter  Google Scholar 

  86. Tibermacine, C., Dony, C., Sadou, S., Fabresse, L.: Software architecture constraints as customizable, reusable and composable entities. In: Babar, M.A., Gorton, I. (eds.) ECSA 2010. LNCS, vol. 6285, pp. 505–509. Springer, Heidelberg (2010). doi:10.1007/978-3-642-15114-9_51

    Chapter  Google Scholar 

  87. Tofan, D., Galster, M., Avgeriou, P.: Capturing tacit architectural knowledge using the repertory grid technique (NIER track). In: ICSE (2011)

    Google Scholar 

  88. Trujillo, S., Azanza, M., Diaz, O., Capilla, R.: Exploring extensibility of architectural design decisions. In: SHARK (2007)

    Google Scholar 

  89. Wu, W., Kelly, T.: Managing architectural design decisions for safety-critical software systems. In: Hofmeister, C., Crnkovic, I., Reussner, R. (eds.) QoSA 2006. LNCS, vol. 4214, pp. 59–77. Springer, Heidelberg (2006). doi:10.1007/11921998_9

    Chapter  Google Scholar 

  90. Zdun, U., Avgeriou, P., Hentrich, C., Dustdar, S.: Architecting as decision making with patterns and primitives. In: SHARK (2008)

    Google Scholar 

  91. Zhu, L., Gorton, I.: UML profiles for design decisions and non-functional requirements. In: SHARK (2007)

    Google Scholar 

  92. Li, Z., Liang, P., Avgeriou, P.: Architectural technical debt identification based on architecture decisions and change scenarios. In: WICSA (2015)

    Google Scholar 

  93. de Boer, R., Lago, P., Telea, A., van Vliet, H.: Ontology-driven visualization of architectural design decisions. In: WICSA/ECSA (2009)

    Google Scholar 

  94. Burge, J.E., Brown, D.C.: SEURAT: integrated rationale management. In: Proceedings of the 30th International Conference on Software Engineering, ICSE (2008)

    Google Scholar 

Download references

Acknowledgement

The authors would like to thank Ralf Reussner for his valuable input. The work has been partially supported by the FP7 European project Seaclouds.

Author information

Authors and Affiliations

  1. Industrial Software Systems, ABB Corporate Research, Ladenburg, Germany

    Zoya Alexeeva

  2. Dip. di Elettronica, Inf. e Bioingegneria, Politecnico di Milano, Milano, Italy

    Diego Perez-Palacin & Raffaela Mirandola

Authors
  1. Zoya Alexeeva
    View author publications

    You can also search for this author in PubMed Google Scholar

  2. Diego Perez-Palacin
    View author publications

    You can also search for this author in PubMed Google Scholar

  3. Raffaela Mirandola
    View author publications

    You can also search for this author in PubMed Google Scholar

Corresponding author

Correspondence to Zoya Alexeeva .

Editor information

Editors and Affiliations

  1. Wageningen University , Wageningen, The Netherlands

    Bedir Tekinerdogan

  2. University of Vienna, Vienna, Austria

    Uwe Zdun

  3. University of Adelaide, Adelaide, South Australia, Australia

    Ali Babar

Rights and permissions

Reprints and permissions

Copyright information

© 2016 Springer International Publishing AG

About this paper

Cite this paper

Alexeeva, Z., Perez-Palacin, D., Mirandola, R. (2016). Design Decision Documentation: A Literature Overview. In: Tekinerdogan, B., Zdun, U., Babar, A. (eds) Software Architecture. ECSA 2016. Lecture Notes in Computer Science(), vol 9839. Springer, Cham. https://doi.org/10.1007/978-3-319-48992-6_6

Download citation

  • DOI: https://doi.org/10.1007/978-3-319-48992-6_6

  • Published:

  • Publisher Name: Springer, Cham

  • Print ISBN: 978-3-319-48991-9

  • Online ISBN: 978-3-319-48992-6

  • eBook Packages: Computer ScienceComputer Science (R0)

Publish with us

Policies and ethics

Search

Navigation