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 |
|
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 |
|
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 |
|
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 |
|
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:
|
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')) |