Skip to main content
Technical Debt Management Metamodel

Overview of the Technical Debt Management metamodel and descriptions and details around components, fields and references.

Simon Field avatar
Written by Simon Field
Updated this week

This metamodel supports the recording, classification, quantification and prioritization of technical debt items. It introduces the Debt Item component type, which can be used to record technical debt that has an impact on any of the following component types:

  • Application

  • Application Module

  • Data Store

  • Technology Service

  • Server

Contents

To gain a more detailed understanding of the value of recording, analyzing and tracking technical debt in Ardoq, and how this Solution has been designed, please read Technical Debt Management: Purpose, Scope and Rationale. With this Solution, you will be able to address the following questions:

  • Which of our applications or other technology assets are impacted by technical debt?

  • Which types of technical debt are most prevalent across our estate?

  • What impacts are we experiencing as a consequence of technical debt?

  • What is the business criticality of the assets that are impacted by technical debt?

  • Which business capabilities and organizational units are impacted by technical debt? (requires implementation of Business Capability Modeling and Realization Solutions)

  • Which quality characteristics are affected by technical debt in our estate?

  • How should we prioritize our effort to address our technical debt?

  • What actions have we agreed to take regarding remediation of technical debt, and by when? (requires implementation of Strategy to Execution Insights & Impacts Solution)

  • Which risks in our risk catalog are impacted by technical debt? (requires implementation of Application Risk Management Solution)

Solution Dependencies

As a minimum, you will wish to record your technical debt items’ impact on Applications. So the Application Lifecycle Management Solution is a prerequisite for implementing this Solution. Connections to assets from other Solutions are optional, but facilitate a more finely grained analysis of technical debt. They include:

  • Application Module (from Application Lifecycle Management Solution)

  • Technology Service, Server, Data Store (from Application Hosting Solution and Technology Portfolio Management Solution)

  • Initiative (from Strategy to Execution Solution)

  • Risk (from Application Risk Management Solution)

  • Business Capability (from Business Capability Realization Solution)

Technical Debt Management Metamodel

Understanding the metamodel

This section explains how technical debt can be represented with the above metamodel; how it is classified with a quality model (such as ISO 25010), how its impact on assets (Applications, Application Modules, Data Stores, Technology Services, Servers) is recorded, how it can be associated with Risks that arise as a consequence of a technical debt item, and with Initiatives that are put in place to remediate debt items.

The Debt Item component type

Debt Item is the component type that is used to represent an individual item of technical debt.

Which assets are impacted by technical debt?

A Debt Item can be specific to one asset, or it can be used to represent a more generic form of technical debt that impacts multiple assets, potentially of different types. The Impacts reference is used to associate the Debt Item with the assets that are impacted by it. Five component types can be impacted by Debt Items:

  • Application

  • Application Module

  • Data Store

  • Technology Service

  • Server

You do not need to have modeled your IT estate using all of these component types to use this Solution, and many organizations choose not to break down applications into their constituent elements or represent supporting technologies as separate components when modeling at an enterprise level. In this situation, your Debt Items will be impacting Application components. However, if you have decomposed your Applications to their constituent modules and datastores, and supporting technology services and servers, then you have the opportunity to associate technical debt more precisely to these individual elements.

You should edit the TD - Debt Item Details Survey so that it aligns with the component types you’ve employed in your metamodel. As provided, questions 4 to 8 invite the user to identify components that are impacted by the debt item for applications, application modules, data stores, technology services and servers respectively. If you have not used some of these component types in your metamodel, you should delete the corresponding questions from the Survey. See Technical Debt Management: Solution Configuration Guide for details of how to do this.

How is technical debt classified?

A Debt Item’s classification is recorded in its Debt Type field. In addition to impacting assets that are subject to the Debt Item, the Debt Item has an Impacts reference link to a Requirement component that belongs to an Information Artifact. We recommend classifying each Debt Item according to a quality model that you’ve adopted as a standard way of describing quality requirements. A quality model is a set of quality characteristics that may be further decomposed into sub-characteristics used to define the quality requirements of a software system or service. It is also sometimes referred to as the set of “quality attributes” that make up the “non-functional requirements” of a system (see Wikipedia “Non-Functional Requirements”).

You might adopt ISO 25010’s quality model for this, or a variation of it. Some organizations choose, instead, to use their Architecture Guiding Principles as a way of classifying technical debt, considering a failure to comply with guiding principles to be a form of technical debt.

For example, using a quality model, a failure to provide a hot-standby environment for a system that requires high availability could be recorded as a debt item that impacts the quality characteristic “Reliability”. Using TOGAF’s example set of Architecture Guiding Principles instead, the same debt item would be recorded as impacting Guiding Principle No. 4 “Business Continuity”.

Three example quality models are provided with the Solution, and instructions on how to configure the Solution to adopt your preferred choice can be found in Technical Debt Management: Solution Configuration Guide. You can, of course, develop your own. If you do so, it should be modeled in the same way as the three provided examples, as an Information Artifact component with Requirement components representing each quality characteristic or principle. See How to represent Policies, Principles, Standards and Frameworks in Ardoq for a detailed description of how to model these types of structured document.

The Debt Type field is automatically populated with the name of the quality model’s Requirement that it impacts.

Quantifying technical debt

Most of the fields in the Debt Item component type are used to quantify the technical debt in one way or another. For more details about the rationale behind these fields, and how they support analysis inspired by both the SQALE Method for Managing Technical Debt and the PAID Model for prioritizing technical debt, see Technical Debt Management: Purpose, Scope and Rationale.

We recommend using the TD - Debt Item Details Survey to maintain the data associated with each Debt Item. The following aspects of technical debt are quantified with field values:

  • A ballpark estimate of the cost of remediating the technical debt item;

  • A ballpark estimate of the annual cost of continuing to live with the technical debt item;

  • An estimate, on a scale of 1 to 5, of the negative business impact of the technical debt item, should the unthinkable happen in a “worst case scenario”;

  • An estimate, on a scale of 1 to 5, of the likelihood that the unthinkable will happen regarding the technical debt item;

  • An estimate of the overall business criticality of the components impacted by the technical debt item.

The “ballpark cost estimates” of the first two items in the list above are achieved by asking the respondent to select an item from a choice of descriptions. These choices are Ardoq’s own suggestion for this approach:

Debt Remediation

Up to 1 week

Up to 1 month

Up to 3 months

Up to 6 months

More than 6 months

Debt Current Impact

Minor inconvenience

Hours per month

Days per month

An extra person

Significant business cost

The aim is to arrive at a rough “ballpark estimate”, to facilitate prioritization, rather than arrive at a precise cost estimate. The input value is then turned into a financial amount with the application of a simple formula that applies a number of days’ cost for each answer, multiplied by a daily rate. These are stored in the calculated numeric fields Debt Remediation Cost and Debt Current Impact Cost. The gremlin code that implements the algorithm is described in the Gremlin code Section below, and can be easily changed in the Ardoq platform, as can the set of options presented to the user in the Survey. See Technical Debt Management: Solution Configuration Guide for more details on how to do this.

The business criticality of each debt item is a calculated field that uses the Criticality field of the Application component. Total Criticality is a calculated field in Debt Item that aggregates the criticality of all Applications that are ultimately impacted by the Debt Item. To count as being “ultimately impacted”, an application is either directly impacted by the Debt Item, or it Is Supported By a component that is itself either directly impacted by the Debt Item, or can trace its connection to a directly impacted component via one or more Is Supported By references to components that are eventually connected to a directly connected component. Child or grandchild components of Applications (such as Application Modules) will pick up the Criticality value of their Application parent. The resulting set of “ultimately impacted” Applications is deduplicated to ensure that Applications which may have multiple paths back to the same Debt Item are not double counted.

In the example below, four of the five Applications (shown with a highlighted Criticality score) are “ultimately impacted” by the Debt Item. The only Application that is not is the one with a Criticality value of 3. Whilst this Application Connects To an Application that is ultimately impacted, the line of “ultimate impact” is only traced through Is Supported By references. The Application in question is not, ultimately, dependent upon the Server that is impacted by the Debt Item. One Application is directly impacted, while three others are indirectly impacted, being able to trace a connection to the impacted Server via one or more Is Supported By references.

This method of calculating Total Criticality allows for the comparison of the business impact of Debt Items that affect underlying business critical infrastructure as well as business critical applications. It is a useful measure when comparing technical debt and deciding which Debt Items to prioritize for remediation action.

Documenting agreed actions

The calculated field Recommended Debt Action applies the PAID Model using the input fields Debt Worst Impact and Debt Probability to arrive at a proposed action: Address, Plan, Delay or Ignore. The input field Debt Action is used to record the agreed action. In addition to the four PAID options, it can also be set to the value of Remediated to indicate that remediation action has been completed and the Debt Item is no longer a live issue. The Review Date field is automatically populated with the date when the TD - Debt Action Survey is submitted, while the Next Review Date field captures the planned future review date for any Debt Items that have a Debt Action value of Delay. See the Process Playbook: Technical Debt Management for details of how to configure and run the automated process of setting, reviewing and tracking actions to address technical debt.

Remediation Activities

If you wish to record the activities being undertaken to address or remediate a Debt Item, you should use the Initiative component from the Strategy to Execution Solution. See the Process Playbook: Technical Debt Management for details of the automated process that you can deploy to capture and track remediation actions. If you follow this process, your action decision is recorded in the field Debt Action. A decision to Address or Plan remediation requires the creation of a new Initiative component, or connection to an existing one, so that there is tangible evidence of the decision being acted upon. The Remediation Active Period field is automatically populated with the Active Period of the linked Initiative. This enables Debt Items to be viewed with the Timeline visualization in the context of all technical debt (including those items for which there is not yet a remediation Initiative).

Associated Risks

Technical debt can often be the underlying cause of a risk. If you have implemented the Application Risk Management Solution you can associate Debt Items with Risk components using the Impacts reference type. This allows you to record and show the impact that technical debt has on your risk landscape. If you do not wish to be able to associate Debt Items with Risk components, you should delete Question 9 in TD - Debt Item Details Survey. See Technical Debt Management: Solution Configuration Guide for details of how to do this. If you’re also tracking remediation actions as described above, you will be able to set an automated reminder to review, reduce or remove the Risk component when the Debt Item has been remediated. See the Process Playbook: Technical Debt Management for details of this.

Debt Item Fields

Field

Field Type

Description

Definition

Debt Type

Calculated Text

Classification of the type of technical debt according to the Quality Characteristic it impacts

Takes the name of the impacted Requirement component

Debt Remediation

List Field

Estimated effort to remediated the debt item

  • Up to 1 week

  • Up to 1 month

  • Up to 3 months

  • Up to 6 months

  • More than 6 months

Debt Remediation Cost

Calculated Number

Estimated cost of remediation based on Debt Remediation value

See Gremlin Code for details

Debt Current Impact

List Field

Estimated business impact of the debt item

  • Minor inconvenience

  • Hours per month

  • Days per month

  • An extra person

  • Significant business cost

Debt Worst Impact

Number Field

Estimated business impact of the technical debt item, should the unthinkable happen in a “worst case scenario”

Scale of 1.0 to 5.0

Debt Current Impact Cost

Calculated Number

Estimated annual cost of continuing to live with the debt item, based on Debt Current Impact value

See Gremlin Code for details

Debt Probability

Number Field

Estimated likelihood that the unthinkable will happen regarding the technical debt item

Scale of 1.0 to 5.0

Recommended Debt Action

Calculated List

Application of the PAID Model using Debt Worst Impact and Debt Probability values

  • Plan

  • Address

  • Ignore

  • Delay

Total Criticality

Calculated Number

Estimated business criticality of this Debt Item

Sum of the Criticality values of all “ultimately impacted” Applications

Debt Action

List Field

Record of agreed Action to address this Debt Item

  • Plan

  • Address

  • Ignore

  • Delay

  • Remediated

Remediation Active Period

Calculated Date Range

The period during which remediation action will occur

Taken from Active Period of Initiative that impacts this Debt Item

Review Date

Date Field

The date when action to address this Debt Item was last reviewed

Populated automatically when TD - Debt Action Survey is submitted

Next Review Date

Date Field

The date when this Debt Item is next due to be reviewed

Set in TD - Debt Action Survey when Debt Action value is Delay

Tech Debt Item References

Reference

Description

Source

Target

Impacts

Represents the direct impact of the Debt Item on a software, hardware or service asset in the IT estate

Debt Item

Any of:

  • Application

  • Application Module

  • Data Store

  • Technology Service

  • Server

Impacts

Identifies the Quality Characteristic that is most impacted by the Debt Item

Debt Item

Requirement

Impacts

Identifies a Risk of which the Debt Item is a potential source

Debt Item

Risk

Impacts

Identifies the Initiative that will remediate the Debt Item

Initiative

Debt Item

Impacts Reference Fields

These two calculated fields are used in the Impacts reference between Debt Item and Risk. They replicate information in the Debt Item so that they are visible to a Survey Broadcast that can be sent to an impacted Risk owner.

Field

Field Type

Description

Definition

Remediated

Calculated checkbox

Records whether the Debt Item (the source of the reference) has a Debt Action value of Remediated

Checked if Debt Item is Remediated, otherwise unchecked

Last Reviewed

Calculated date time

Records the Review Date value of the Debt Item (the source of the reference) i.e. when the Debt Action was last updated

Replicates Review Date from the Debt Item

Gremlin code

This section contains the Gremlin code used to implement the Calculated Fields of the Technical Debt Solution.

Debt Type (field in Debt Item)

This code populates the field with the name of the Requirement that is Impacted by the Debt Item. It is assumed that the Requirement represents a quality characteristic in a quality model that has been defined in Ardoq following the guidance given in How to represent Policies, Principles, Standards and Frameworks in Ardoq. Note that there should only be one Impacted Requirement component, but if there is more than one, the code will return the name of the first of these.

// returns the name of the first Requirement that this Debt Item impacts

g.V(ids).

project('id', 'name', 'value').

by(id).

by('name').

by(__.out('Impacts').hasLabel('Requirement').coalesce(values('name')))

Debt Remediation Cost (field in Debt Item)

This code applies the following simple algorithm to generate an estimated remediation cost from the list field Debt Remediation. First a daily cost amount is specified in the variable dailyRate. Then the selected list item is converted to a number of days’ effort:

  • 4 days effort for the value Up to 1 week

  • 16 days effort for the value Up to 1 month

  • 48 days effort for the value Up to 3 months

  • 96 days effort for the value Up to 6 months

  • 192 days effort for the value More than 6 months

  • 0 days effort for any other value

The value returned is the number of days’ effort multiplied by the daily rate.

dailyRate = 500

g.V(ids).

project('id', 'name', 'value').

by(id).

by('name').

by(

choose(has('debt_remediation', 'Up to 1 week'), constant(4 * dailyRate),

choose(has('debt_remediation', 'Up to 1 month'), constant(16 * dailyRate),

choose(has('debt_remediation', 'Up to 3 months'), constant(48 * dailyRate),

choose(has('debt_remediation', 'Up to 6 months'), constant(96 * dailyRate),

choose(has('debt_remediation', 'More than 6 months'), constant(192 * dailyRate),

constant (0)))))))

Debt Current Impact Cost (field in Debt Item)

This code applies the following simple algorithm to generate an estimated annual impact cost from the list field Debt Current Impact. First a daily cost amount is specified in the variable dailyRate. Then the selected list item is converted to a number of days’ effort:

  • 4 days loss for the value Minor inconvenience

  • 12 days loss for the value Hours per month

  • 48 days loss for the value Days per month

  • 192 days loss for the value An extra person

  • 384 days loss for the value Significant business cost

  • 0 days loss for any other value

The value returned is the number of days’ effort multiplied by the daily rate.

dailyRate = 500

g.V(ids).

project('id', 'name', 'value').

by(id).

by('name').

by(

choose(has('debt_current_impact', 'Minor inconvenience'), constant(4 * dailyRate),

choose(has('debt_current_impact', 'Hours per month'), constant(12 * dailyRate),

choose(has('debt_current_impact', 'Days per month'), constant(48 * dailyRate),

choose(has('debt_current_impact', 'An extra person'), constant(192 * dailyRate),

choose(has('debt_current_impact', 'Significant business cost'), constant(384 * dailyRate),

constant (0)))))))

Recommended Debt Action (field in Debt Item)

This code implements the Gartner PAID Model. Note that where a score is at the midpoint of the range (i.e. 3) it is considered to be above the line. So a Debt Item with a Debt Worst Impact of 3 and a Debt Probability of 3 will be placed in the top right quadrant (i.e. Address).

g.V(ids).

project('id', 'name', 'value').

by(id).

by('name').

by(

choose(has('debt_worst_impact', gte(3)),

// either Plan or Address

choose(has('debt_probability', gte(3)),

constant('Address'), constant('Plan')),

// either Ignore or Delay

choose(has('debt_probability', gte(3)),

constant('Delay'), constant('Ignore'))))

Total Criticality (field in Debt Item)

This code sums the Criticality values of all “ultimately impacted” Applications. First it follows the Impacts references from the Debt Item to all impacted Applications, Application Modules, Technology Services, Servers and Data Stores. Then it recursively follows incoming Is Supported By references, stopping a line of search when it reaches an Application component. Note that it uses “emit().repeat(out('ardoq_parent'))” to go up the parent tree to check if the component is a descendent of an Application, and also that it deduplicates the set of Applications ("dedup()") to ensure that Application components are not double counted.

def toInteger = {

try {

return it.get().toInteger();

} catch (NumberFormatException e) {

return 0;

}

}

g.V(ids).

project('id', 'name', 'value').

by(id).

by('name').

by(out('Impacts').hasLabel('Application', 'Application Module','Technology Service',

'Server','Data Store').

union(

emit().repeat(__.in('Is Supported By')).until(hasLabel('Application')).emit().

repeat(out('ardoq_parent'))).dedup().values('criticality').map(toInteger).sum())

Remediation Active Period (field in Debt Item)

This code populates Remediation Active Period with the start and end dates of the Initiative that Impacts this Debt Item. Note that it is not possible to edit this code. If you wish to change it, you will have to delete the Field and recreate it with new code. See the article Calculated Date Ranges for more details on this.

g.V(ids).

project('id', 'name', 'value').

by(id).

by('name').

by(__.in('Impacts').hasLabel('Initiative').values('active_period_start_date'))

g.V(ids).

project('id', 'name', 'value').

by(id).

by('name').

by(__.in('Impacts').hasLabel('Initiative').values('active_period_end_date'))

Remediated (field in Impacts reference)

This field is used by the Broadcast TD - Reduce Risk to identify that a Debt Item that impacts a Risk has been remediated. Because the scope of the Broadcast is the Risk component (and not the Debt Item), the fields in the Debt Item are not available to the filter conditions. By replicating information in the reference between the two, it becomes visible to the Broadcast and is used to pinpoint only Risks that are impacted by Debt Items that have recently become remediated.

g.E(ids).

project('id', 'value').

by(id).

by(choose(outV().has('debt_action', 'Remediated'), constant(true), constant(false)))

Last Reviewed (field in Impacts reference)

This field is used by the Broadcast TD - Reduce Risk to identify when the survey TD - Debt Action was last submitted. Because the scope of the Broadcast is the Risk component (and not the Debt Item), the fields in the Debt Item are not available to the filter conditions. By replicating information in the reference between the two, it becomes visible to the Broadcast and is used to pinpoint only Risks that are impacted by Debt Items that have recently become remediated.

g.E(ids).

project('id','value').

by(id).

by(outV().values('review_date'))

Did this answer your question?