G Model ARTICLE IN PRESS - mit. richh/writings/doc-framework-   Architecture decision

download G Model ARTICLE IN PRESS - mit. richh/writings/doc-framework-   Architecture decision

of 26

  • date post

  • Category


  • view

  • download


Embed Size (px)

Transcript of G Model ARTICLE IN PRESS - mit. richh/writings/doc-framework-   Architecture decision

  • Please cite this article in press as: van Heesch, U., et al., A documentation framework for architecture decisions. J. Syst. Software (2011),doi:10.1016/j.jss.2011.10.017

    ARTICLE IN PRESSG ModelJSS-8817; No. of Pages 26The Journal of Systems and Software xxx (2011) xxxxxx

    Contents lists available at SciVerse ScienceDirect

    The Journal of Systems and Software

    j our na l ho mepage: www.elsev ier .com/ locate / j ss

    A documentation framework for architecture decisions

    U. van Heescha,b,, P. Avgerioua, R. Hilliardca University of Groningen, Groningen, The Netherlandsb Fontys University of Applied Sciences, Venlo, The Netherlandsc Consulting Software Systems Architect, Massachusetts, USA

    a r t i c l e i n f o

    Article history:Received 1 May 2011Received in revised form 15 October 2011Accepted 17 October 2011Available online xxx

    Keywords:Software architectureArchitecture decisionsArchitecture knowledge managementArchitectural viewpointsCase studyArchitecture framework

    a b s t r a c t

    In this paper, we introduce a documentation framework for architecture decisions. This frameworkconsists of four viewpoint definitions using the conventions of ISO/IEC/IEEE 42010, the new interna-tional standard for the description of system and software architectures. The four viewpoints, a DecisionDetail viewpoint, a Decision Relationship viewpoint, a Decision Chronology viewpoint, and a DecisionStakeholder Involvement viewpoint satisfy several stakeholder concerns related to architecture decisionmanagement.

    With the exception of the Decision Stakeholder Involvement viewpoint, the framework was evaluatedin an industrial case study. The results are promising, as they show that decision views can be createdwith reasonable effort while satisfying many of the stakeholder concerns in decision documentation.

    2011 Elsevier Inc. All rights reserved.

    1. Introduction

    With the growing complexity and size of software-intensivesystems, software architecture has become increasingly important.While architecture is traditionally understood as the design of thesystem itself, manifested mainly in design elements and their form,Perry and Wolf recognized the importance of (design-)rationale asan integral part of the software architecture. They defined softwarearchitecture as follows:

    Software Architecture = {Elements, Forms, Rationale} (Perry andWolf, 1992)

    Kruchten adopted this definition of software architecture as a start-ing point for the 4+1 View Model framework (Kruchten, 1995). Inthis framework, each of the five views addresses various systemconcerns and determines the organization of a set of architecturalelements, the forms and patterns used, and the rationale behindthose architectural choices. This concept of documenting softwarearchitecture as a set of views that correspond to viewpoint (VP) def-initions and address system concerns was adopted and generalizedin IEEE Std 1471:2000 (IEEE, 2000), and further elaborated by thearchitecture community (e.g., Clements et al., 2002; Rozanski andWoods, 2005). However, as in Kruchtens 4+1, the importance of

    Corresponding author at: University of Groningen, Groningen, The Netherlands.E-mail addresses: uwe@vanheesch.net, u.vanheesch@fontys.nl (U. van Heesch),

    paris@cs.rug.nl (P. Avgeriou), r.hilliard@computer.org (R. Hilliard).

    documenting decisions and their rationale along with the selectedarchitectural concepts was only mentioned, but little guidance wasoffered on how to document decisions.

    Bosch emphasized the importance of documenting architectureas a set of architecture decisions (ADs) (Bosch, 2004). In contrast tothe aforementioned approaches, design decisions as an explicit partof the software architecture description provide insight into thereasoning process and record the rationale behind design decisions.The concept of architecture decisions has been incorporated intoISO/IEC/IEEE 42010, (ISO, 2011), which is the international revisionof IEEE Std 1471:2000 (IEEE, 2000).

    Today, the perspective of looking at software architecture interms of a set of architecture decisions is widely recognized.Authors have proposed templates for the information contentthat is important to capture about decisions (e.g., Jansen andBosch, 2005; Tyree and Akerman, 2005), and various models andtools to capture and manage architecture decisions have beenproposed (Tang et al., 2010). Several approaches incorporate thedocumentation of architecture decisions in architecture practiceand subsequently capture and organize architecture decisions toaddress various concerns, such as traceability and architecturalconformance (Babar et al., 2009).

    There are currently three main approaches to documentingarchitecture decisions: decision templates, decision models, andannotations. We argue that all three approaches satisfy somedecision-related concerns, but none of them succeeds in satisfyingall concerns. Shortcomings of architecture decision documenta-tion approaches are not surprising: as with traditional architecture

    0164-1212/$ see front matter 2011 Elsevier Inc. All rights reserved.doi:10.1016/j.jss.2011.10.017


  • Please cite this article in press as: van Heesch, U., et al., A documentation framework for architecture decisions. J. Syst. Software (2011),doi:10.1016/j.jss.2011.10.017

    ARTICLE IN PRESSG ModelJSS-8817; No. of Pages 262 U. van Heesch et al. / The Journal of Systems and Software xxx (2011) xxxxxx

    views, there is not a single way of documenting architecture deci-sions that frames all concerns of all stakeholders in an adequateand useful manner. We propose that multiple dedicated viewpointsshould be defined that focus on framing specific decision-relatedconcerns.

    In this paper, we propose a documentation framework consist-ing of four viewpoints for architecture decisions: a Decision Detailviewpoint, a Decision Relationship viewpoint, a Decision Chronol-ogy viewpoint and a Decision Stakeholder Involvement viewpoint.Each viewpoint is dedicated to framing specific decision-relatedconcerns. At the same time, each viewpoint is integrated with theother viewpoints through a common metamodel to offer a morecomplete picture of decisions and their rationale. The frameworkproposed here is useful out of the box, but it can also serve asa basis for customization or extension by adding new decision-related viewpoints. One extension of the framework currentlybeing investigated adds a viewpoint dedicated to decision-makingforces (see Section 6). This viewpoint also builds upon the cur-rent framework metamodel. Apart from the Decision StakeholderInvolvement viewpoint, all viewpoints were validated in an indus-trial case study with very promising results.

    The rest of this paper is organized as follows. Section 2 presentsdecision-related concerns. In Section 3, we briefly outline theproposed viewpoints including an example view for each of theviewpoints.1 In Section 4, we report on an industrial case study,which was conducted to validate the viewpoints. Section 5 sum-marizes related work. Section 6 presents our conclusions and ideasfor future work.

    2. Concerns related to architecture decisions

    Architecture decisions should be documented to complementarchitectural design with rationale. Yet, how to capture decisions isstill subject to discussion. This is mainly because there is no consen-sus on which stakeholder concerns must be addressed by a decisiondocumentation approach. A concern, as used here, is any interestin a system on the part of its stakeholders. Each concern poses aquestion or issue that the architecture description, in this case thearchitecture decision documentation, should be able to answer.

    In recent years, many use cases for architectural knowledgemanagement have been published in the literature. We arguethat decisions are one type of architectural knowledge. Therefore,we have analyzed three recent publications containing architec-tural knowledge management (AKM) use cases (Liang et al., 2009;Kruchten et al., 2006; Jansen et al., 2007) to identify and deriveconcerns for architecture decision documentation. Table 1 showsthe resulting concerns.2 The concerns were functionally groupedand, where possible, ordered according to the authors estimation oftheir importance. The actual importance of the concerns, however,often depends on the specific needs of the concrete stakeholder.

    The analysis procedure, as well as a complete table with the ana-lyzed use cases, the derived concerns, and the activities performedto derive the respective concerns can be found in Appendix A.

    Next, the authors assigned the concerns to typical stakehold-ers. Table 2 shows the results. Most concerns were assigned toarchitects and reviewers, because these stakeholders are frequentlyusing architecture documentation in their daily work. Note that theassignment of the concerns took place based on typical tasks thatthe stakeholders perform in software projects. It could be argued

    1 The whole documentation framework in terms of a unified metamodel, the com-plete viewpoint definitions, and the correspondences between those viewpoints arespecified in Appendix C.

    2 A decision sub-graph, as used in concern C23, is a subset of a bigger set ofinterrelated decisions.

    Table 1Concerns for architecture decision documentation.

    Code Concern

    C1 What decisions have been made?C2 What is the curre