The Technical Debt Management Solution is designed to interact with components that are part of other Solutions. Debt Item components can impact Application, Application Module, Data Store, Technology Service or Server components. Debt Items can also be associated with related Risk components, and Initiative components can be used to track remediation efforts.

But it would be wrong to assume that use of all of these component types, and the Solutions where they originate, are prerequisites for the adoption of the Technical Debt Solution. As a minimum, this Solution expects to have a set of Application components that might be impacted by technical debt. Connection to all of the other component types listed above, and shown in the metamodel diagram, is optional, but a few changes will need to be made to remove reference to those that are not in use.

This document will guide you through the simple process of adjusting the Technical Debt Solution on initial deployment to accommodate the component types you have in your metamodel, and those you don't. Guidance is also given on how to adopt a different quality model as the basis for classifying Debt Items, and how to update the questions and associated algorithms that turns responses into cost estimates.

Whilst the aim of this document is to provide a guide to initial configuration before you have created any Debt Item components, changes to the range of component types that can be impacted by Debt Items can be made at any time. But once you have some Debt Items, changes that would alter field values in Debt Items, for example by changing allowable values to the List Fields, will trigger the need for more substantial refactoring.

Technical Debt Solution Metamodel

By default, Debt Item components can have an Impacts reference to any of the following technology component types:

If your metamodel only uses a subset of these, you will need to change the Survey TD - Debt Item Details. This is because the Survey uses Reference Questions to create references from the Debt Item to the impacted assets. A single reference question cannot be used to create references to multiple component types, so the Survey contains a separate Reference Question for each component type that might be impacted by the Debt Item. To update the Survey to suit your metamodel:

For example, if you only use Application and Data Store to model your technology estate, then you should remove questions 5, 7 and 8 from the Survey.

The Solution has been designed to link up with the Application Risk Management Solution. This allows Debt Items to be associated with Risk components in recognition that technical debt is often a source of risk. The value of this association is that the owner of a linked Risk component can be notified when its source Debt Item has been remediated. This will allow them to review the risk, perhaps reducing its impact or likelihood in the light of the remediation of the related technical debt.

However, if you are not using Risk components in your metamodel, you will want to make some changes to simplify the Technical Debt Solution:

Associating Debt Items with Initiative components from the Strategy to Execution Solution facilitates the tracking of your efforts to remediate technical debt. If you do not use the Initiative component type in your metamodel, you should make the following changes:

The Technical Debt Solution uses a quality model to classify each Debt Item. When the Debt Item is created with the TD - Debt Item Details Survey, an Impacts reference is created from it to a Requirement component that represents a quality characteristic. The name of this component is then used to populate the calculated field Debt Type in the Debt Item.

As discussed in Technical Debt Management: Purpose, Scope and Rationale, some organizations choose to use a set of Architecture Guiding Principles as the quality model that is used to classify technical debt. Three example Quality Models are included in the Quality Models Workspace provided with the Solution. Question 3 in the Survey TD - Debt Item Details is a Reference question, What type of Debt Item is this?, that asks the user to select a quality characteristic from the quality model. You will note that this only presents the list of Requirement components that are children of the Information Artifact named Quality Model. This is achieved with an advanced search.

If you wish to use a different quality model, you should use the Survey Builder to edit TD - Debt Item Details and change the advanced search criteria in Question 3 so that only components that are children of your chosen quality model are offered as options. Check also that your chosen quality model is in the workspace nominated for the question.

The Debt Item component type contains two fields for cost estimates: Debt Remediation Cost is an estimate of the cost of remediating the debt, and Debt Current Impact Cost is an estimate of the annual cost of living with the debt (the “annual interest payment”). The Survey TD - Debt Item Details is used to create or update a Debt Item. But it does not directly ask for financial amounts. Instead, five options are presented in each case that aim to provide a rough sizing of the amount. So the value of the field Debt Remediation is used by the Calculated Field Debt Remediation Cost, and the value of the field Debt Current Impact is used by the Calculated Field Debt Current Impact Cost. The field options and the algorithms that translate these to a financial number that are provided with the Solution are shown below:

To change the options offered to the user of the Survey, you must edit the corresponding List Field in Ardoq (Debt Remediation or Debt Current Impact). When you select Edit field properties for the field, the following panel appears on the right, where you can replace the List options with ones of your own choosing:

Once you have saved your new list options, you will need to edit the gremlin code of the corresponding Cost calculated field so that it references your new list options. This is also where you may change the default daily rate and the number of days allocated to each of your list options. Edit the field whose calculation you wish to update, scroll to the bottom of the panel and choose the Edit icon button:

This will open the calculation code, which you can update with a different daily rate, list options or number of days. When you’ve made your changes, you can test the calculation then apply it, and your new calculation will be applied.

The following table lists the assets that make up the Solution along with the Workspaces that are referenced. Deploying the Solution will cause all of the relevant components to be created if they are not already present. Other sections of this document indicate how to adapt the solution to work without some component types. If you also choose to delete the corresponding Workspaces, you will need to edit the Assets that reference those workspaces and delete the reference.