Skip to content

Update TechnicalDebtMonitoring.md #305

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 12 commits into
base: main
Choose a base branch
from
Open

Update TechnicalDebtMonitoring.md #305

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
2cd21a6
Update TechnicalDebtMonitoring.md
ld-at-work Jun 4, 2025
6630bca
Update TechnicalDebtPolicy.md
ld-at-work Jun 4, 2025
a31fa43
Update TechnicalDebtPolicy.md
ld-at-work Jun 4, 2025
647cc65
Update TechnicalDebtPolicy.md
ld-at-work Jun 4, 2025
a827540
Update TechnicalDebtPolicy.md
ld-at-work Jun 4, 2025
7495aa7
Update TechnicalDebtMonitoring.md
ld-at-work Jun 4, 2025
660c563
Update TechnicalDebtPolicy.md
ld-at-work Jun 4, 2025
2a8090b
Update TechnicalDebtMonitoring.md
ld-at-work Jun 4, 2025
5ed0c80
Update software-engineering-policies/TechnicalDebt/TechnicalDebtPolic…
ld-at-work Jun 4, 2025
597f537
Update TechnicalDebtPolicy.md
ld-at-work Jun 4, 2025
d30c552
Update TechnicalDebtMonitoring.md
ld-at-work Jun 4, 2025
8f7d981
Update TechnicalDebtMonitoring.md
ld-at-work Jun 4, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 34 additions & 34 deletions software-engineering-policies/TechnicalDebt/TechnicalDebtMonitoring.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,49 +2,49 @@

## Pre-requisites

- Each project will need a `Technical debt` work item type in their process.
- This has to be added by a process editor.
- if you are using the default **DGf** template then the project will have a Technical debt type already.
- Each project will need a `Technical Debt` work item type in their process.
- This has to be added by a process editor.
- if you are using the default **DGf** template then the project will have a Technical Debt type already.
- Each project will need a "Technical Debt" dash board.
- An aggregation of all the "Technical Debt" will be visible on a central dashboard.

![Dashboard Technical Debt](./dashboard_TD_V1.png)

## Work item fields

* A **Technical debt** work item type **MUST** be created in target project.
* Add new Details section with the following fields (use existing field, do not create a new field):
* Primary Product or Service
* there may be several interconnecting products but which is the main one, if needed, create a separate TD item for each product if they would be addressed separately.
* Technical priority
* TD1 - High business/technical value, high risk debt that needs to be paid off ASAP (a Security tag should automatically be considered for a TD1 prioritisation).
* TD2 - High business/technical value (cost reduction, blocker removing, maintainability improvement), lower risk, a change that should be worked on when time/opportunity permits and is not something that can be accepted or supported long term.
* TD3 - Tech debt that has been accepted as a risk but through paying off would add value through improving usability, maintainability, reliability or performance.
* TD4 - Accepted risk from the business, safe to leave until service reaches end of life. Worth tracking in case developers are working in the area and can complete as quick wins.
* Technical debt type
* Architectural – Tightly coupled systems (lots of criss-crossed dependencies), * restrictive to extension or automation
* Code – Low quality code or ineffective patterns
* Knowledge – lack of documentation or inaccessible documentation
* Automation – Lack of automated tasks forcing manual intervention (Testing, deployments, * backup/restore)
* Testing – Unknown or unrecorded test scenarios, lack of test coverage
* Maintenance – Out-of-support products, usually leading to security vulnerabilities
* Process - inefficient or wasteful process steps, this could be related to practice or * tooling
* Security - Known and exploitable vulnerabilities
* Technical debt impact
* Increased time to deliver
* Unplanned work
* Inaccurate planning
* Disengaged Development teams
* Longer times to recover
* Instability
* Security Concerns
* Add a new section called Status
* Add field for Scheduled Release

## Using `Technical debt` work items
- A **Technical Debt** work item type **MUST** be created in target project.
- Add new Details section with the following fields (use existing field, do not create a new field):
- Primary Product or Service
- there may be several interconnecting products but which is the main one, if needed, create a separate TD item for each product if they would be addressed separately.
- Technical priority
- TD1 - High business/technical value, high risk debt that needs to be paid off ASAP (a Security tag should automatically be considered for a TD1 prioritisation).
- TD2 - High business/technical value (cost reduction, blocker removing, maintainability improvement), lower risk, a change that should be worked on when time/opportunity permits and is not something that can be accepted or supported long term.
- TD3 - Tech debt that has been accepted as a risk but through paying off would add value through improving usability, maintainability, reliability or performance.
- TD4 - Accepted risk from the business, safe to leave until service reaches end of life. Worth tracking in case developers are working in the area and can complete as quick wins.
- Technical Debt type
- Architectural - Tightly coupled systems (lots of criss-crossed dependencies), restrictive to extension or automation
- Code - Low quality code or ineffective patterns
- Knowledge - lack of documentation or inaccessible documentation
- Automation - Lack of automated tasks forcing manual intervention (Testing, deployments, backup/restore)
- Testing - Unknown or unrecorded test scenarios, lack of test coverage
- Maintenance - Out-of-support products, usually leading to security vulnerabilities
- Process - inefficient or wasteful process steps, this could be related to practice or tooling
- Security - Known and exploitable vulnerabilities
- Technical Debt impact
- Increased time to deliver
- Unplanned work
- Inaccurate planning
- Disengaged Development teams
- Longer times to recover
- Instability
- Security Concerns
- Add a new section called Status
- Add field for Scheduled Release
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

end file with newline

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

there is one:
image


## Using `Technical Debt` work items

Once created the work item can be added to the team boards as part of the process backlog level, to allow tracking at the "Requirements backlog" level or as a separate backlog level, similar to features and epics.

The Technical debt portfolio backlog will need to be added to each team view as needed.
The Technical Debt portfolio backlog will need to be added to each team view as needed.

![Portfolio Technical Debt](./Porfolio_TD_V1.png)
89 changes: 44 additions & 45 deletions software-engineering-policies/TechnicalDebt/TechnicalDebtPolicy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,53 +1,53 @@
# Technical Debt Policy

All UKHO employees engaged with digital product development should develop a basic understanding of technical debt, how it's generated, its impacts on the business and how it can be paid off.
All UKHO employees engaged with digital product development should develop a basic understanding of Technical Debt, how it's generated, its impacts on the business and how it can be paid off.

All individuals who identify technical debt should record it as per the following strategy. Where the individual cannot, the information should be passed to the relevant team, product manager or service owner to be raised.
All individuals who identify Technical Debt should record it as per the following strategy. Where the individual cannot, the information should be passed to the relevant team, product manager or service owner to be raised.

## Objective

To provide the UKHO with a detailed and expansive data set about technical debt across the organisation, enabling greater business intelligence at all levels of the organisation for more informed and effective decision making.
To provide the UKHO with a detailed and expansive data set about Technical Debt across the organisation, enabling greater business intelligence at all levels of the organisation for more informed and effective decision making.

## Technical Debt Definition

Deficiencies in internal quality or capability that make a product/service/application more costly to modify, extend or maintain.

## Technical Debt Types

Each product **MUST** maintain a register of technical debt within its Azure DevOps project.
Each product **MUST** maintain a register of Technical Debt within its Azure DevOps project.

This should include all types of technical debt, i.e.:
This should include all types of Technical Debt, i.e.:

* Architectural – Tightly coupled systems (lots of criss-crossed dependencies), restrictive to extension or automation
* Code – Low quality code or ineffective patterns
* Knowledge – lack of documentation or inaccessible documentation
* Automation – Lack of automated tasks forcing manual intervention (Testing, deployments, backup/restore)
* Testing – Unknown or unrecorded test scenarios, lack of test coverage
* Maintenance – Out-of-support products, usually leading to security vulnerabilities
* Process - inefficient or wasteful process steps, this could be related to practice or tooling
* Security - Known and exploitable vulnerabilities
- Architectural – Tightly coupled systems (lots of criss-crossed dependencies), restrictive to extension or automation
- Code – Low quality code or ineffective patterns
- Knowledge – lack of documentation or inaccessible documentation
- Automation – Lack of automated tasks forcing manual intervention (Testing, deployments, backup/restore)
- Testing – Unknown or unrecorded test scenarios, lack of test coverage
- Maintenance – Out-of-support products, usually leading to security vulnerabilities
- Process - inefficient or wasteful process steps, this could be related to practice or tooling
- Security - Known and exploitable vulnerabilities
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Technical - (heading below)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

line?


## Technial Debt Impact
## Technical Debt Impact

Technical debt impacts various aspects of an application's life cycle, this is often dictated by the type of technical debt but common impacts you can expect from outstanding technical debt are:
Technical Debt impacts various aspects of an application's life cycle, this is often dictated by the type of Technical Debt but common impacts you can expect from outstanding Technical Debt are:

* Increased time to deliver
* Unplanned work
* Inaccurate planning
* Disengaged Development teams
* Longer times to recover
* Instability
* Security Concerns
- Increased time to deliver
- Unplanned work
- Inaccurate planning
- Disengaged Development teams
- Longer times to recover
- Instability
- Security Concerns

---

## Raising Technical Debt

Technical debt identified in the current sprint but not being resolved as part of present work **MUST** be raised as a `Technical debt` work item type in the relevant area of Azure DevOps. The relevant location is based on whether the technical debt is related to a product or a team.
Technical Debt identified in the current sprint but not being resolved as part of present work **MUST** be raised as a `Technical Debt` work item type in the relevant area of Azure DevOps. The relevant location is based on whether the Technical Debt is related to a product or a team.

Ideally even if technical debt is going to be resolved immediately raising it is good for understanding its impact on UKHO work and identifying that technical debt was discovered.
Ideally even if Technical Debt is going to be resolved immediately raising it is good for understanding its impact on UKHO work and identifying that Technical Debt was discovered.

When raising technical debt, please add the following information to the Technical Debt work item:
When raising Technical Debt, please add the following information to the Technical Debt work item:

### Title

Expand All @@ -57,14 +57,14 @@ When raising technical debt, please add the following information to the Technic

The description of the Technical Debt item must include the following as a minimum:

* The repository the Technical Debt lives within (a link to the repo would be good but the name would suffice)
* Description of the issue in as much detail as you can provide, including class/file names if this can be included
* A proposed solution or ideas for a fix **
* Cost/Benefit and risk of the Technical Debt item, simply as a "why should this be fixed?/How long would it take?"
- The repository the Technical Debt lives within (a link to the repo would be good but the name would suffice)
- Description of the issue in as much detail as you can provide, including class/file names if this can be included
- A proposed solution or ideas for a fix **
- Cost/Benefit and risk of the Technical Debt item, simply as a "why should this be fixed?/How long would it take?"

### Strategy

* A **Technical debt** work item type **MUST** be created in target project. Using queries and dashboads it is then possible to monitor Technical Debt.
- A **Technical Debt** work item type **MUST** be created in target project. Using queries and dashboards it is then possible to monitor Technical Debt.

![Example Tech Debt work item](./Example_TD_V4.PNG)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

extra blank line (ln 85)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Enclose bare links in angle brackets (ln 107-109)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

missing apostrophe (ln 113)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

where?

Expand All @@ -74,39 +74,38 @@ The description of the Technical Debt item must include the following as a minim

### How this meshes with RAID

A technical debt work item should be created, even if the team is not planning on addressing the technical debt within the current sprint. We advise that teams carrying out RAID analysis and create technical debt work items in addition to this analysis. Consider that some technical debt items have been long lived in the past this will help support or future development teams consider the technical debt for future resolution and when planning.
A Technical Debt work item should be created, even if the team is not planning on addressing the Technical Debt within the current sprint. We advise that teams carrying out RAID analysis and create Technical Debt work items in addition to this analysis. Consider that some Technical Debt items have been long lived in the past this will help support or future development teams consider the Technical Debt for future resolution and when planning.

## Refining Technical Debt

If the technical debt item doesn't meet any of the above it should be considered as debt with little or no value to resolution and considered for removal from the backlog.
If the Technical Debt item doesn't meet any of the above it should be considered as debt with little or no value to resolution and considered for removal from the backlog.

If during refinement an imminent issue is discovered (e.g. old Technical Debt, with high risk, which is time sensitive, but has not been addressed) this should be refined and flagged to a senior Solution Architect, Product Manager and relevant Delivery Manager.


## Technical Debt Tracking/Monitoring

There is automated near-realtime monitoring of technical debt available for all projects within the UKHydro Azure DevOps tenant. This is made available by the DDC technical debt Prometheus exporter and relies on accurately tracked technical debt PBIs. For information on this exporter and the technology used please refer to the [technical debt monitoring](../TechnicalDebt/TechnicalDebtMonitoring.md) document.
There is automated near-realtime monitoring of Technical Debt available for all projects within the UKHydro Azure DevOps tenant. This is made available by the DDC Technical Debt Prometheus exporter and relies on accurately tracked Technical Debt PBIs. For information on this exporter and the technology used please refer to the [Technical Debt monitoring](../TechnicalDebt/TechnicalDebtMonitoring.md) document.

## FAQ

**When is a defect (bug) technical debt?**
Defects (also known as bugs) are only considered technical debt if the decision has been made to accept or otherwise leave the defect unresolved. In this case the defect should be marked as technical debt following the provided guidance. If the defect is something intended to be fixed within current or next sprint, then do not mark it as technical debt.
**When is a defect (bug) Technical Debt?**
Defects (also known as bugs) are only considered Technical Debt if the decision has been made to accept or otherwise leave the defect unresolved. In this case the defect should be marked as Technical Debt following the provided guidance. If the defect is something intended to be fixed within current or next sprint, then do not mark it as Technical Debt.

**How do I balance technical debt?**
**How do I balance Technical Debt?**

>‘Technical debt’ is any compromise you make on quality to develop something quickly in the short-term. The extra effort (or ‘interest’) required to improve what you’ve built is something you’ll have to make (or ‘pay back’) in future.
>‘Technical Debt’ is any compromise you make on quality to develop something quickly in the short-term. The extra effort (or ‘interest’) required to improve what you’ve built is something you’ll have to make (or ‘pay back’) in future.
>
>As your technical debt grows, your code will become more difficult to work with. This means adding new features will get harder, take longer and introduce more bugs.
>As your Technical Debt grows, your code will become more difficult to work with. This means adding new features will get harder, take longer and introduce more bugs.
>
>If you decide it’s necessary to compromise on quality so you can deliver something quickly, your team needs to understand the implications of taking on technical debt. You **MUST** record technical debt even if you don't plan on resolving it. You **should** also agree a plan for keeping it under control.
>If you decide it’s necessary to compromise on quality so you can deliver something quickly, your team needs to understand the implications of taking on Technical Debt. You **MUST** record Technical Debt even if you don't plan on resolving it. You **should** also agree a plan for keeping it under control.
>
>Learn one of the ways [GOV.UK managed technical debt](https://insidegovuk.blog.gov.uk/2013/12/10/paying-down-technical-debt-in-the-departments-and-policy-publishing-platform/).
>Learn one of the ways [GOV.UK managed Technical Debt](https://insidegovuk.blog.gov.uk/2013/12/10/paying-down-technical-debt-in-the-departments-and-policy-publishing-platform/).

## Additional Reading

- https://martinfowler.com/bliki/TechnicalDebt.html
- https://martinfowler.com/bliki/EstimatedInterest.html
- https://martinfowler.com/bliki/TechnicalDebtQuadrant.html
- [https://martinfowler.com/bliki/TechnicalDebt.html]
- [https://martinfowler.com/bliki/EstimatedInterest.html]
- [https://martinfowler.com/bliki/TechnicalDebtQuadrant.html]

## Legacy Technical Debt Tracking

Expand All @@ -118,4 +117,4 @@ Each team should have its own set of queries and a dashboard. These will be copi

## Points of Contact

* Policy Owner - Principal Support Developer
- Policy Owner - Principal Support Developer
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

end file with newline

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see a line?
image