Architecture Viewpoints for Documenting Architectural Technical Debt

Introduction

Architecture Viewpoints for Documenting Architectural Technical Debt is a chapter in Economics-Driven Software Architecture.  The authors are Zengyang Li, Peng Liang, and Paris Avgeriou (LLA).  In this chapter, the authors propose a set of viewpoints which are meant to facilitate the documentation of architectural technical debt.  This blog post provides a summary and commentary.

There are three stated contributions for this work.  They are:

1. Identify architectural technical debt stakeholders and their concerns.
2. Propose their architecture viewpoints.
3. Provide evidence for the effectiveness of their viewpoints.

Following a common pattern for articles on technical debt, the authors begin by describing what they mean by their use of the term.  In this case technical debt is taken to mean the compromise of some quality attribute (QA) in exchange for a business advantages.  Quality attributes can include things like modularity, encapsulation, maintainability or evolvability.  Business advantages can include things like time to market and cost savings.  Architectural technical debt (ATD), specifically is when architectural decisions are made that incur or repay technical debt.  As seen in this work, architectural debt normally influences maintainability or evolvability.

Architectural Debt Viewpoints

Before introducing their viewpoints, the authors justify their importance, saying:

To facilitate ATD management (ATDM), ATD needs to be documented, so that it becomes explicit and visible to involved stakeholders. If ATD is not documented, architecture decision making is very likely to ignore it and its impact on candidate decisions. Consequently, undocumented ATD items will keep collecting interest (i.e., effort required to fix the corresponding design issues), leading to a prohibitive cost in system maintenance and evolution. To the best of our knowledge, there are no approaches for systematically documenting ATD.

After briefly describing the viewpoints, some background and a more detailed explanation follow.  After this more complete description, a case study which evaluated the viewpoints is reported.  The proposed architecture viewpoints are:

1. ATD Detail viewpoint - provides descriptive details about instances of ATD.
2. ATD Decision viewpoint - describes the relationship between ATD instances and architectural decisions.
3. ATD Stakeholder Involvement viewpoint - describes stakeholder responsibilities for ATD management (ATDM) and shows who did what.
4. ATD Distribution viewpoint - describes the distribution of ATD among instances and how the amount of ATD changes between checkpoints.
5. ATD-related component viewpoint - describes relationships between system elements and ATD instances.
6. ATD Chronological viewpoint - shows evolution of ATD instances over time.

Background

After introducing their own work, LLA provide some general background about ATD and technical debt documentation.  They note that ISO/IEC 250101 describes the quality attribute, maintainability, to include the following subcomponents: { modularity, reusability, analyzability, modifiability, and testability} and they define evolvability to mean, "ease of adding new functional and non-functional requirements.”  They go on to assert that there is little literature on technical debt documentation, and none on documentation of architecture technical debt.  Of the literature that exists on documenting technical debt, LLA asserts that all proposed documentation templates included the following fields:

• Unique identifier
• Location
• Responsible developer
• Type of Technical Debt
• Description

They go on to mention that these fields are also commonly included:

• Principal 
• Interest
• Interest probability
• Interest standard deviation
• Name
• Context
• Intentionality
• Correlation with other technical debt items
• Propagation rules.

LLA credit Guo and Seaman for the notion that some technical debt items correlate with each other, and Holvitie and Leppanen for the concept of propagation rules - implementation components which cause technical debt to spread.

Next, they cite from their own work, Architectural debt management in value-oriented architecting, to introduce the ATDM process and stakeholders, and to describe ATDM activities for these stakeholders.  Cells filled in blue show a pairing where the stakeholder is involved with the ATDM activity.  Cells in white show an absence of involvement.

	Steps of Architectural Technical Debt Management
Stakeholders		Identification	Measurement	Prioritization	Monitoring	Repayment
	Architects
	Architecture evaluators
	Project Managers
	Development Team
	Customers
	Stakeholder concerned with this aspect of ATDM			Stakeholder not concerned with this aspect of ATDM.

LLA present these roles in textual format, not tabular, but by putting them into a grid, some surprises become apparent.  First, although customers are described as stakeholders, they seem to have no role in ATDM.  Second, the only stakeholders who are concerned with monitoring ATD are architects.  Finally, the only role for project managers appears to be prioritization.

ATD Viewpoints and Concerns

LLA found stakeholder concerns about ATD, first by adapting from generic technical debt literatue and second by deriving them from the ATDM activities described above.  In all, there were 21 concerns, as seen in their Table 1.  (Side note... it is amusing, but not very informative, to listen to the @Voice Read Aloud app read these tables.)

LLA describes each of the viewpoints in detail, and I suggest reading it.  This post can only manage a cursory summary of each.

ATD Detail viewpoint:  The ATD Detail viewpoint describes detailed information about a system's architectural technical debt.  This viewpoint contains descriptive fields like ID, Name, Version, Date, Priority, and Intentionality; stakeholder fields such as "Incurred by" and "Repaid by"; tracking fields like the Compromised QA, Status, Rationale, and History; and quantitative fields including Cost, Principal, and Interest.

ATD Decision viewpoint: This viewpoint describes architecture decisions which have incurred or repaid technical debt.  These decisions might have been made by architects, designers, or developers.  Following the protocol from Mcconnel's widely cited 2007 blog post, these decisons can be intentional or unintentional.

ATD-related Component viewpoint: The ATD-related Component viewpoint shows bidirectional mapping between instances of technical debt and the components that need to be modified in order to repay them.

ATD Distribution viewpoint: This viewpoint tracks iterative changes to the accumulated ATD as changes are made to a system.  This viewpoint also enables the total level of ATD to be tracked against a threshold of acceptability.  This threshold is defined by the project manager.

ATD Stakeholder Involvement viewpoint: The ATD Stakeholder Involvement viewpoint describes the stakeholders' responsibilities for managing instances of ATD.  This includes vies of ATD items, actions, and stakeholders within a single iteration of system evolution.

ATD Chronological viewpoint: The final viewpoint shows the change to instances of ATD over time.  The functional difference between this view and the ATD Distribution viewpoint is that it focuses on changes to particular instances of ATD, not the accumulated total.  This viewpoint also shows the changes to the cost and benefit of the measured ATD item.

Case Study

In the case study, at a large Chinese telecommunications firm, LLA sought to answer three research questions:

RQ1: How easy is it to understand the ATD viewpoints?
RQ2: How easy is it to collect the required information for generating ATD views governed by the ATD viewpoints and to document ATD views with the gathered information?
RQ3: Do ATD views effectively support stakeholders to understand the ATD?

To accomplish this, nine participants attended a four hour workshop, during which they were asked to make use of the viewpoints in their own system, made up of 760,000 lines of code.  This table describes the data collection process.

Phase	Task
START
Part 1 – Preparation	Recall and document past architectural decisions
Part 2 – Workshop	Present ATD Viewpoints, identification, and measurement approach.
	Collect change scenarios
	Identify and measure ATD based on architecture decisions and change scenarios.
	Document the identified ATD items
	Prioritize the identified ATD items
Part3 – Interview	Participant questionnaire and semi-structured interview
END

In conclusion, here is what the researchers found with regards to their three research questions:

RQ1:  The viewpoints were generally well understood, but that the ATD Detail viewpoint had some room for improvement.  The ATD-related Component viewpoint scored best.
RQ2: Ease of use scores were low, but LLA argue that the time requirement was not excessive in relation to the knowledge gained.  They also note that practitioners can save time by choosing to omit aspects of the viewpoints.
RQ3: These viewpoints can help participants to reach a consensus perspective on a software system's architectural health.  All participants expressed a willingness to use the ATD Detail viewpoint in the future.

Commentary

For the most part, LLA achieved their three intended contributions:

1. Identify architectural technical debt stakeholders and their concerns.
2. Propose their architecture viewpoints.
3. Provide evidence for the effectiveness of their viewpoints.

Overall, the research was thorough and the viewpoints seem to be understandable and useful, but I finish the document with two questions.  First, I wonder if the analysis of stakeholder roles and concerns was incomplete.  Second, as a long time IT professional, I wonder if the authors are overly optimistic about the level of effort results from RQ2 in the case study.

With regards to the stakeholders, I already noted the peculiarities that only the architect monitors ATD, and that customer stakeholders have no role to play in management of ATD.  Additionally, in their discussion of the ATD Distribution Viewpoint, LLA assigned the following concerns to customers:

C2 How much ATD does a software system have?
C16 How fast is the total ATD benefit and cost of a software system changing?
(Page 11, Table 9)

I wonder why C21 isn't also a concern of the customer:

C21 Is ATD in a software system under acceptable level?

Pertaining to the ease of use, in eleven categories, all level of effort scores came in lower than 8 out of 10, with a couple as low as 5.2.  If presented with a tool like that in some of my already overloaded workplaces of the past, I don't imagine enthusiastic adoption.  It's easy for these study participants to say that they'll use a tool again, but maybe not so easy to actually do it.  Although the participants expressed a willingness to use the ATD Detail Viewpoint in the future, I am curious as to whether these case study participants followed their words with action.

Some items which might effect level of effort include the learning curve, the level of boredom associated with repetition, and the degree of automation.  In this study, excel templates were used for the documentation.  LLA acknowledged the need for a better tool in future work (it is mildly ironic to find this instance of technical debt reported in a technical debt study).  It is possible that stakeholders further along the learning curve with a better implementation might find the viewpoints' level of effort to be more agreeable.