Skip to content
Switch branches/tags
Go to file
Cannot retrieve contributors at this time
title: How to track technical debt
last_reviewed_on: 2021-06-04
review_in: 6 months
# <%= %>
While planning for the technical work we do in GDS, we need a common language
between technologists and product people to describe the scale and scope of
technical debt.
The language should enable communication of the benefits of individual pieces
of work that pay down tech debt. It should also enable us to be clearer about
the consequences of not doing something, or leaving a piece of work in a
certain state, and should allow us to track the reduction or accumulation of
technical debt over time.
The process used for tracking debt should not add significant overhead to
planning, and assigning a rating to a piece of technical debt should be quick
and simple.
## Example consequences of tech debt
- Harder to patch security vulnerabilities
- Harder to implement new features
- Harder to onboard new developers
- Consumes too many compute resources
- Too closely coupled to an architecture
- Causes too many support tickets
- Creates too much chore work
- Difficult to debug issues
- Inconsistent architecture
## Example causes of tech debt
- Out of date dependencies
- Hardcoded configuration
- Component has too many responsibilities
- Long running test suite
- Manual deployment task
- Missing documentation
- No admin interface
- Not using lessons learnt since build
## Classifying and measuring
Classifying tech debt uses two factors: the current impact of the consequence
and the effort required to remove the cause. Both are subjectively measured as
high (red), medium (amber) or low (green) with a justification and explanation
of the cause and consequence.
These are subjectively combined into an overall high/medium/low risk rating,
with the reason for the relative weighting also recorded. This rating signifies
the risk and associated cost with not dealing with the item right now. In some
circumstances (such as an upcoming planned rewrite or retirement) we would
accept a high risk as the item would go away naturally anyway. For this reason,
the risks do not necessarily map directly to priorities.
This is similar to how risks are recorded in a Risk Register. High, medium and
low ratings are given for impact and likelihood along with a combined overall
rating based on a decision about the relative importance of the impact and
likelihood. The higher the overall rating, the more the programme should be
concerned about it.
The impact of a piece of technical debt, and the effort required to remove the
cause of it, will change over time. Review recorded items of technical debt at
appropriate periods. For example: if a problematic system was not being
actively worked on at the time a piece of debt was originally recorded, it may
have a low impact rating; if it subsequently becomes worked on again, you
should review the impact.
## Process
Items of Technical Debt should be recorded on a Trello board per product. See
[GOV.UK's board]( as an example.
The product's technical leadership will triage these on a fortnightly basis,
agree the assigned ratings and add them to the correct category. They should
also review each item every 3 months.
The product's technical leadership (for example, Technical Architects, Technical Leads, Lead
Developers) should use these lists during conversations with Product and
Delivery Managers when prioritising work. Technical debt existing on the
register doesn’t necessarily mean it will be paid down at any point, only that
GOV.UK is conscious of its existence and will take it into account in product
Tracking debt as it gets created will follow the same process, with a link to a
Trello card on a team’s backlog for the story that created it. The debt review
process doesn’t make decisions on whether the creation of the debt is the
correct thing to do, that decision stays with the product team.
If something is too small in scope to be included on the board, it should be
recorded in the relevant repository's Github issues. Tech leads should review
these regularly as part of prioritisation.
## Example
> ### Whitehall has its own upload management system
> Cause: Whitehall’s system for handling uploads of PDFs, CSVs and images
> from publishing users is different to the Asset Manager application used by
> Specialist Publisher and others. This is due to it being developed in
> isolation from another system.
> Consequences:
> - Inconsistent architecture
> - Too closely coupled to physical disk
> - Causes support tickets due to delay in processing attachments
> Impact of debt: High due to confusion, operational restrictions and
> support burden.
> Effort to pay down: High due to the technical effort involved in changing
> Whitehall to talk to Asset Manager, implementing missing features in Asset
> Manager and migrating existing assets.
> Overall rating: High