Industrial Implementation of a Documentation Framework for Architectural Decisions

Architecture decisions are often not explicitly documented in practice but reside in the architect's mind as tacit knowledge, even though explicit capturing and documentation of architecture decisions has been associated with a multitude of benefits. As part of a research collaboration with ABB, we developed a tool to document architecture decisions. This tool is an add-in for Enterprise Architect and is an implementation of a viewpoint-based decision documentation framework. To validate the add-in, we conducted an exploratory case study with ABB architects. In the study, we assessed the status quo of architecture decision documentation, identified architects' expectations of the ideal decision documentation tool, and evaluated the new add-in. We found that although awareness of decision documentation is increasing at ABB, several barriers exist that limit the use of decisions in practice. Regarding their ideal tool, architects want a descriptive and efficient approach. Supplemental features like reporting or decision sharing are requested. The new add-in, was well-perceived by the architects. As a result of the study, we propose a clearer separation of problem, outcomes, and alternatives for the decision documentation framework.