Tool-support for Architecture Decision Documentation

The perspective of looking at software architecture as a set of architecture decisions is widely recognized in research. However, in practice architecture decisions are often not explicitly documented but reside in the architect’s mind as tacit knowledge or are only implicit in the models that the architect creates. Even though explicit capturing and documentation of architecture decisions has been associated with a multitude of benefits such as avoiding knowledge vaporization, supporting change impact estimation, increasing system understanding and knowledge sharing, and facilitating architecture evaluation. In cooperation with a large multinational industrial corporation, we developed a tool that should facilitate the documentation of architecture decisions, as there is currently no standardized decision documentation approach or tool that is suitable for company- wide use. The tool is an extension to Sparx Systems’ Enterprise Architect and is based on a theoretical framework comprised of five architectural viewpoints. The framework has been developed by the Software Engineering and Architecture group of the University of Groningen. We conducted an exploratory case study at our industry partner. The objective of this study was to assess the status quo of architecture decision documentation, to identify expectations of the ideal documentation approach, and to evaluate the advantages and limitations of the developed extension. The findings of the case-study suggest that the developed extension allows documenting decisions in a user-friendly way and provides valuable support to capture architecture decisions. However, we also identified important improvements, such as a clear separation of problem, outcome and alternatives within the used meta-model. The study also showed that decisions are receiving rising awareness but that a lack of tool-support and a lack of standard approach for ADD limit the documentation and the use of decisions in practice.