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.
Access this chapter
Tax calculation will be finalised at checkout
Purchases are for personal use only
Similar content being viewed by others
References
Ozkaya, I., Wallin, P., Axelsson, J.: Architecture knowledge management during system evolution: observations from practitioners. In: SHARK (2010)
Taylor, R.N., Medvidovic, N., Dashofy, E.M.: Software Architecture: Foundations, Theory, and Practice. Wiley, New York (2009)
Kruchten, P., Capilla, R., Dueas, J.: The decision view’s role in software architecture practice. IEEE Softw. 26, 36–42 (2009)
Burge, J.E., Carroll, J.M., McCall, R., Mistrik, I.: Rationale-Based Software Engineering. Springer, Heidelberg (2008)
Tang, A., Babar, M.A., Gorton, I., Han, J.: A survey of architecture design rationale. J. Syst. Softw. 79, 1792–1804 (2006)
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)
Manteuffel, C., Tofan, D., Koziolek, H., Goldschmidt, T., Avgeriou, P.: Industrial implementation of a documentation framework for architectural decisions. In: WICSA (2014)
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)
Burge, J.E., Brown, D.C.: Software engineering using RATionale. J. Syst. Softw. 81, 395–413 (2008)
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
Dragomir, A., Lichter, H., Budau, T.: Systematic architectural decision management: a process-based approach. In: WICSA (2014)
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)
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
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)
Babar, M., de Boer, R., Dingsoyr, T., Farenhorst, R.: Architectural knowledge management strategies: approaches in research and industry. In: SHARK (2007)
Rozanski, N., Woods, E.: Software Systems Architecture: Working with Stakeholders Using Viewpoints and Perspectives. Addison-Wesley Professional, Upper Saddle River (2009)
Tyree, J., Akerman, A.: Architecture decisions: demystifying architecture. IEEE Softw. 22(2), 19–27 (2005)
Jansen, A., Bosch, J.: Software architecture as a set of architectural design decisions. In: 5th Working IEEE/IFIP Conference on Software Architecture, WICSA (2005)
Kruchten, P.: An ontology of architectural design decisions in software intensive systems. In: 2nd Groningen Workshop on Software Variability (2004)
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)
Shahin, M., Liang, P., Khayyambashi, M.: Architectural design decision: existing models and tools. In: WICSA/ECSA (2009)
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
Bu, W., Tang, A., Han, J.: An analysis of decision-centric architectural design approaches. In: SHARK (2009)
Henttonen, K., Matinlassi, M.: Open source based tools for sharing and reuse of software architectural knowledge. In: WICSA/ECSA (2009)
Hoorn, J.F., Farenhorst, R., Lago, P., van Vliet, H.: The lonesome architect. J. Syst. Softw. 84(9), 1424–1435 (2011)
Kitchenham, B.: Procedures for performing systematic reviews. Keele University Technical report TR/SE-0401 and NICTA Technical report 0400011T.1 (2004)
de Boer, R.C., Farenhorst, R.: In search of ‘architectural knowledge’. In: SHARK (2008)
Koziolek, H.: Performance evaluation of component-based software systems: a survey. Perform. Eval. 67, 634–658 (2010)
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)
University of Illinois: Software Engineering Conferences (2014)
IEEE: IEEE Digital Library. http://ieeexplore.ieee.org/search/advsearch.jsp
DBLP: Search DBLP Computer Science Bibliography. http://dblp.uni-trier.de/search/
ACM: ACM Digital Library. http://dl.acm.org/advsearch.cfm
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)
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
Eloranta, V.P., Hylli, O., Vepsalainen, T., Koskimies, K.: TopDocs: using software architecture knowledge base for generating topical documents. In: WICSA/ECSA (2012)
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
Buchgeher, G., Weinreich, R.: Automatic tracing of decisions to architecture and implementation. In: WICSA (2011)
Durdik, Z., Reussner, R.: On the appropriate rationale for using design patterns and pattern documentation. In: QoSA (2013)
Jansen, A., van der Ven, J., Avgeriou, P., Hammer, D.K.: Tool support for architectural decisions. In: WICSA (2007)
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
Navarro, E., Cuesta, C., Perry, D.: Weaving a network of architectural knowledge. In: WICSA/ECSA (2009)
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)
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
Miller, J.A., Ferrari, R., Madhavji, N.H.: An exploratory study of architectural effects on requirements decisions. J. Syst. Softw. 83, 2441–2455 (2010)
Shahin, M., Liang, P., Khayyambashi, M.R.: Improving understandability of architecture design through visualization of architectural design decision. In: SHARK (2010)
That, M.T.T., Sadou, S., Oquendo, F.: Using architectural patterns to define architectural decisions. In: WICSA/ECSA (2012)
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)
Cui, X., Sun, Y., Mei, H.: Towards automated solution synthesis and rationale capture in decision-centric architecture design. In: WICSA (2008)
Miesbauer, C., Weinreich, R.: WICSA/ECSA (2012)
Mirakhorli, M., Cleland-Huang, J.: Transforming trace information in architectural documents into re-usable and effective traceability links. In: SHARK (2011)
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)
Szlenk, M., Zalewski, A., Kijas, S.: Modelling architectural decisions under changing requirements. In: WICSA/ECSA (2012)
Nowak, M., Pautasso, C.: Goals, questions and metrics for architectural decision models. In: SHARK (2011)
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
Tang, A., Jin, Y., Han, J.: A rationale-based architecture model for design traceability and reasoning. J. Syst. Softw. 80, 918–934 (2007)
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
Bortis, G.: Informal software design knowledge reuse. In: ICSE (2010)
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
Miksovic, C., Zimmermann, O.: Architecturally significant requirements, reference architecture, and metamodel for knowledge management in information technology services. In: WICSA (2011)
Lago, P., Avgeriou, P., Capilla, R., Kruchten, P.: Wishes and boundaries for a software architecture knowledge community. In: WICSA (2008)
Komiya, S.: A model for the recording and reuse of software design decisions and decision rationale. In: Software Reuse: Advances in Software Reusability (1994)
Babar, M.A., Gorton, I.: A tool for managing software architecture knowledge. In: SHARK (2007)
de Boer, R., Van Vliet, H.: Experiences with semantic wikis for architectural knowledge management. In: WICSA (2011)
Wang, W., Burge, J.E.: Using rationale to support pattern-based architectural design. In: SHARK (2010)
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)
Carignano, M., Gonnet, S., Leone, H.: A model to represent architectural design rationale. In: WICSA/ECSA (2009)
Che, M.: An approach to documenting and evolving architectural design decisions. In: Proceedings of the 2013 International Conference on Software Engineering, ICSE (2013)
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
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
Egyed, A., Wile, D.: Support for managing design-time decisions. IEEE Trans. Softw. Eng. 32, 299–314 (2006)
Garcia, A., Batista, T., Rashid, A., Sant’Anna, C.: Driving and managing architectural decisions with aspects. SIGSOFT Softw. Eng. Notes 31, 6 (2006)
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
Gu, Q., Lago, P.: SOA process decisions: new challenges in architectural knowledge modeling. In: SHARK (2008)
Gu, Q., van Vliet, H.: SOA decision making - what do we need to know. In: SHARK (2009)
Habli, I., Kelly, T.: Capturing and replaying architectural knowledge through derivational analogy. In: SHARK (2007)
Harrison, N.B., Avgeriou, P., Zdun, U.: Using patterns to capture architectural decisions. IEEE Softw. 24, 38–45 (2007)
Jansen, A., Bosch, J., Avgeriou, P.: Documenting after the fact: recovering architectural design decisions. J. Syst. Softw. 81, 536–557 (2008)
Jansen, A., Avgeriou, P., van der Ven, J.S.: Enriching software architecture documentation. J. Syst. Softw. 82, 1232–1248 (2009)
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
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
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)
Sinnema, M., van der Ven, J.S., Deelstra, S.: Using variability modeling principles to capture architectural knowledge. SIGSOFT Softw. Eng. Notes 31, 5 (2006)
Soliman, M., Riebisch, M., Zdun, U.: Enriching architecture knowledge with technology design decisions. In: WICSA (2015)
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
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
Tofan, D., Galster, M., Avgeriou, P.: Capturing tacit architectural knowledge using the repertory grid technique (NIER track). In: ICSE (2011)
Trujillo, S., Azanza, M., Diaz, O., Capilla, R.: Exploring extensibility of architectural design decisions. In: SHARK (2007)
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
Zdun, U., Avgeriou, P., Hentrich, C., Dustdar, S.: Architecting as decision making with patterns and primitives. In: SHARK (2008)
Zhu, L., Gorton, I.: UML profiles for design decisions and non-functional requirements. In: SHARK (2007)
Li, Z., Liang, P., Avgeriou, P.: Architectural technical debt identification based on architecture decisions and change scenarios. In: WICSA (2015)
de Boer, R., Lago, P., Telea, A., van Vliet, H.: Ontology-driven visualization of architectural design decisions. In: WICSA/ECSA (2009)
Burge, J.E., Brown, D.C.: SEURAT: integrated rationale management. In: Proceedings of the 30th International Conference on Software Engineering, ICSE (2008)
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
Corresponding author
Editor information
Editors and Affiliations
Rights 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)