Design Decision Documentation: A Literature Overview

Conference paper
Part of the Lecture Notes in Computer Science book series (LNCS, volume 9839)


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.


Decision Documentation Capture Design Decisions Categorical Attributes Industrial Applicability Knowledge Management Architecture 
These keywords were added by machine and not by the authors. This process is experimental and the keywords may be updated as the learning algorithm improves.



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


  1. 1.
    Ozkaya, I., Wallin, P., Axelsson, J.: Architecture knowledge management during system evolution: observations from practitioners. In: SHARK (2010)Google Scholar
  2. 2.
    Taylor, R.N., Medvidovic, N., Dashofy, E.M.: Software Architecture: Foundations, Theory, and Practice. Wiley, New York (2009)CrossRefGoogle Scholar
  3. 3.
    Kruchten, P., Capilla, R., Dueas, J.: The decision view’s role in software architecture practice. IEEE Softw. 26, 36–42 (2009)CrossRefGoogle Scholar
  4. 4.
    Burge, J.E., Carroll, J.M., McCall, R., Mistrik, I.: Rationale-Based Software Engineering. Springer, Heidelberg (2008)CrossRefzbMATHGoogle Scholar
  5. 5.
    Tang, A., Babar, M.A., Gorton, I., Han, J.: A survey of architecture design rationale. J. Syst. Softw. 79, 1792–1804 (2006)CrossRefGoogle Scholar
  6. 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. 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. 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)CrossRefGoogle Scholar
  9. 9.
    Burge, J.E., Brown, D.C.: Software engineering using RATionale. J. Syst. Softw. 81, 395–413 (2008)CrossRefGoogle Scholar
  10. 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. 11.
    Dragomir, A., Lichter, H., Budau, T.: Systematic architectural decision management: a process-based approach. In: WICSA (2014)Google Scholar
  12. 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)CrossRefGoogle Scholar
  13. 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 CrossRefGoogle Scholar
  14. 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)CrossRefGoogle Scholar
  15. 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. 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. 17.
    Tyree, J., Akerman, A.: Architecture decisions: demystifying architecture. IEEE Softw. 22(2), 19–27 (2005)CrossRefGoogle Scholar
  18. 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. 19.
    Kruchten, P.: An ontology of architectural design decisions in software intensive systems. In: 2nd Groningen Workshop on Software Variability (2004)Google Scholar
  20. 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)CrossRefzbMATHGoogle Scholar
  21. 21.
    Shahin, M., Liang, P., Khayyambashi, M.: Architectural design decision: existing models and tools. In: WICSA/ECSA (2009)Google Scholar
  22. 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 CrossRefGoogle Scholar
  23. 23.
    Bu, W., Tang, A., Han, J.: An analysis of decision-centric architectural design approaches. In: SHARK (2009)Google Scholar
  24. 24.
    Henttonen, K., Matinlassi, M.: Open source based tools for sharing and reuse of software architectural knowledge. In: WICSA/ECSA (2009)Google Scholar
  25. 25.
    Hoorn, J.F., Farenhorst, R., Lago, P., van Vliet, H.: The lonesome architect. J. Syst. Softw. 84(9), 1424–1435 (2011)CrossRefGoogle Scholar
  26. 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. 27.
    de Boer, R.C., Farenhorst, R.: In search of ‘architectural knowledge’. In: SHARK (2008)Google Scholar
  28. 28.
    Koziolek, H.: Performance evaluation of component-based software systems: a survey. Perform. Eval. 67, 634–658 (2010)CrossRefGoogle Scholar
  29. 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)CrossRefGoogle Scholar
  30. 30.
    University of Illinois: Software Engineering Conferences (2014)Google Scholar
  31. 31.
  32. 32.
    DBLP: Search DBLP Computer Science Bibliography.
  33. 33.
    ACM: ACM Digital Library.
  34. 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. 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 CrossRefGoogle Scholar
  36. 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. 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 CrossRefGoogle Scholar
  38. 38.
    Buchgeher, G., Weinreich, R.: Automatic tracing of decisions to architecture and implementation. In: WICSA (2011)Google Scholar
  39. 39.
    Durdik, Z., Reussner, R.: On the appropriate rationale for using design patterns and pattern documentation. In: QoSA (2013)Google Scholar
  40. 40.
    Jansen, A., van der Ven, J., Avgeriou, P., Hammer, D.K.: Tool support for architectural decisions. In: WICSA (2007)Google Scholar
  41. 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 CrossRefGoogle Scholar
  42. 42.
    Navarro, E., Cuesta, C., Perry, D.: Weaving a network of architectural knowledge. In: WICSA/ECSA (2009)Google Scholar
  43. 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)CrossRefGoogle Scholar
  44. 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 CrossRefGoogle Scholar
  45. 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)CrossRefGoogle Scholar
  46. 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. 47.
    That, M.T.T., Sadou, S., Oquendo, F.: Using architectural patterns to define architectural decisions. In: WICSA/ECSA (2012)Google Scholar
  48. 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)CrossRefGoogle Scholar
  49. 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. 50.
    Miesbauer, C., Weinreich, R.: WICSA/ECSA (2012)Google Scholar
  51. 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. 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)CrossRefGoogle Scholar
  53. 53.
    Szlenk, M., Zalewski, A., Kijas, S.: Modelling architectural decisions under changing requirements. In: WICSA/ECSA (2012)Google Scholar
  54. 54.
    Nowak, M., Pautasso, C.: Goals, questions and metrics for architectural decision models. In: SHARK (2011)Google Scholar
  55. 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 CrossRefGoogle Scholar
  56. 56.
    Tang, A., Jin, Y., Han, J.: A rationale-based architecture model for design traceability and reasoning. J. Syst. Softw. 80, 918–934 (2007)CrossRefGoogle Scholar
  57. 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 CrossRefGoogle Scholar
  58. 58.
    Bortis, G.: Informal software design knowledge reuse. In: ICSE (2010)Google Scholar
  59. 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 CrossRefGoogle Scholar
  60. 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. 61.
    Lago, P., Avgeriou, P., Capilla, R., Kruchten, P.: Wishes and boundaries for a software architecture knowledge community. In: WICSA (2008)Google Scholar
  62. 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. 63.
    Babar, M.A., Gorton, I.: A tool for managing software architecture knowledge. In: SHARK (2007)Google Scholar
  64. 64.
    de Boer, R., Van Vliet, H.: Experiences with semantic wikis for architectural knowledge management. In: WICSA (2011)Google Scholar
  65. 65.
    Wang, W., Burge, J.E.: Using rationale to support pattern-based architectural design. In: SHARK (2010)Google Scholar
  66. 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)CrossRefGoogle Scholar
  67. 67.
    Carignano, M., Gonnet, S., Leone, H.: A model to represent architectural design rationale. In: WICSA/ECSA (2009)Google Scholar
  68. 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. 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 CrossRefGoogle Scholar
  70. 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 CrossRefGoogle Scholar
  71. 71.
    Egyed, A., Wile, D.: Support for managing design-time decisions. IEEE Trans. Softw. Eng. 32, 299–314 (2006)CrossRefGoogle Scholar
  72. 72.
    Garcia, A., Batista, T., Rashid, A., Sant’Anna, C.: Driving and managing architectural decisions with aspects. SIGSOFT Softw. Eng. Notes 31, 6 (2006)CrossRefGoogle Scholar
  73. 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. 74.
    Gu, Q., Lago, P.: SOA process decisions: new challenges in architectural knowledge modeling. In: SHARK (2008)Google Scholar
  75. 75.
    Gu, Q., van Vliet, H.: SOA decision making - what do we need to know. In: SHARK (2009)Google Scholar
  76. 76.
    Habli, I., Kelly, T.: Capturing and replaying architectural knowledge through derivational analogy. In: SHARK (2007)Google Scholar
  77. 77.
    Harrison, N.B., Avgeriou, P., Zdun, U.: Using patterns to capture architectural decisions. IEEE Softw. 24, 38–45 (2007)CrossRefGoogle Scholar
  78. 78.
    Jansen, A., Bosch, J., Avgeriou, P.: Documenting after the fact: recovering architectural design decisions. J. Syst. Softw. 81, 536–557 (2008)CrossRefGoogle Scholar
  79. 79.
    Jansen, A., Avgeriou, P., van der Ven, J.S.: Enriching software architecture documentation. J. Syst. Softw. 82, 1232–1248 (2009)CrossRefGoogle Scholar
  80. 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 CrossRefGoogle Scholar
  81. 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 CrossRefGoogle Scholar
  82. 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)CrossRefGoogle Scholar
  83. 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. 84.
    Soliman, M., Riebisch, M., Zdun, U.: Enriching architecture knowledge with technology design decisions. In: WICSA (2015)Google Scholar
  85. 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 CrossRefGoogle Scholar
  86. 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 CrossRefGoogle Scholar
  87. 87.
    Tofan, D., Galster, M., Avgeriou, P.: Capturing tacit architectural knowledge using the repertory grid technique (NIER track). In: ICSE (2011)Google Scholar
  88. 88.
    Trujillo, S., Azanza, M., Diaz, O., Capilla, R.: Exploring extensibility of architectural design decisions. In: SHARK (2007)Google Scholar
  89. 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 CrossRefGoogle Scholar
  90. 90.
    Zdun, U., Avgeriou, P., Hentrich, C., Dustdar, S.: Architecting as decision making with patterns and primitives. In: SHARK (2008)Google Scholar
  91. 91.
    Zhu, L., Gorton, I.: UML profiles for design decisions and non-functional requirements. In: SHARK (2007)Google Scholar
  92. 92.
    Li, Z., Liang, P., Avgeriou, P.: Architectural technical debt identification based on architecture decisions and change scenarios. In: WICSA (2015)Google Scholar
  93. 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. 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

Copyright information

© Springer International Publishing AG 2016

Authors and Affiliations

  1. 1.Industrial Software SystemsABB Corporate ResearchLadenburgGermany
  2. 2.Dip. di Elettronica, Inf. e BioingegneriaPolitecnico di MilanoMilanoItaly

Personalised recommendations