Capturing Software Architecture Design Rationale Through Decision Stories

Abstract

Within Software Architecture, there is no universal template for capturing design rationale in (architectural) decisions, many templates exist within the literature and industry. Research has shown there is a growing need for documenting design rationale. However, architects do not always document their rationale due to time and budget constraints. This research proposes a decision template that stimulates architect to capture design rationale. Building on a decision template from existing work, it answers the research question: how can design rationale of decisions be captured effectively? Through a literature review and expert interviews, concrete requirements for decision documentation are derived. The Decision Story, a lightweight template to document decisions is designed. The template is validated through case studies, expert interviews, and a focus group. Results show the Decision Story captures the rationale aspects architects and the literature deem most important, is easy in its use due to being compact and intuitive, can be used in different visualisations, is easily modified to specific projects, fulfils the needs of stakeholders, is able to expose gaps in the decision process of architect, and leads to a higher quality decision. Further research is needed to test the effectiveness of the Decision Story in practice.