Blog

Technical Debt Records

/ software architecture, technical debt, project management

Have you ever wondered how to keep track of all the technical debt in your software projects? In this post, we will explore the concept of Technical Debt Records and how they can improve the way we manage the technical debt of our projects

What is Technical Debt?

Technical debt comes in different forms, for example:

  • Using outdated libraries.
  • Poorly written code.
  • Lack of documentation.

It is important to know how much technical debt we have accumulated. Since, if we have a lot, it may be impossible to manage it effectively. Before reaching a state of complete unsustainability, we must make plans to resolve technical debt adequately. To do this, it is necessary to understand how serious it is and how it affects us and locate it. This will help us decide what we should solve first.

Types of Technical Debt

Technical debt can be classified into four categories:

  • Architecture: Arises when the system structure is not optimal, leading to issues such as poor maintenance, scalability, or performance. It can be due to initial design choices or evolve as the system grows.
  • Technological Gap: It is the gap between the current technology used in a project and the latest stable technology available. For example: Using outdated libraries or frameworks, can degrade performance and scalability.
  • Infrastructure: derived from the systems that support the software, such as servers, storage, and networks. Not optimal infrastructure can produce bottlenecks and reduce efficiency.
  • Code: is related to the quality of the source code itself, for example: code smells, or duplication. This makes the code more difficult to understand, maintain, and change.

What is a Technical Debt Record?

Technical Debt Records allow us to document and track technical debt within our software project. By maintaining Technical Debt Records, we can prioritize, manage, and address these issues, ensuring the overall health and maintainability of the software.

Each Technical Debt Record should include the following elements:

  1. Description: A clear and concise explanation of the technical debt.
  2. Reason: The reason behind incurring technical debt, such as:
    • time limitations.
    • lack of resources.
    • temporary solutions.
  3. Impact: An assessment of the potential consequences of not addressing technical debt, including the effects on performance, maintainability, or scalability.
  4. Location: The exact location of the affected code, file, and line number.
  5. Priority: A prioritization of technical debt based on its impact and urgency.
  6. Owner: The person or team responsible.
  7. Date Incurred: The date the technical debt was identified or incurred.
  8. Estimated effort: An estimate of the effort in time and resources required to resolve the technical debt.
  9. Resolution Plan: The plan to address technical debt, including next steps, dependencies, and any approvals or resources required.
  10. Status: The current status of the technical debt record, such as "Open", "In Progress" or "Resolved".

Example of a Technical Debt Record

Field Details
Description Refactor the user authentication module to improve security.
Reason Quick implementation to meet a release deadline.
Impact Potential security vulnerabilities and difficult maintenance.
Location auth/user_auth_module.py, lines 45-120.
Priority High
Owner Backend Development Team
Date Incurred 2024-07-10
Estimated Effort 20 hours
Resolution Plan Implement industry-standard encryption and token handling.
Status Open

Technical Debt Tracking Tools

There are a lot of tools to track technical debt, for example:

The following template can be used in GitHub in your project, you just need to add a new issue template to your project in .github/ISSUE_TEMPLATE/technical_debt.md:

---  
name: Technical Debt  
about: Create a technical debt record.  
title: ''  
labels: technical-debt  

---  

**Describe the technical debt**  

> _A clear and concise explanation of the technical debt._  

**Reason**  

> _The reason behind incurring technical debt, such as:_  
> - _time limitations._  
> - _lack of resources._  
> - _temporary solutions._  

**Impact**  

> _An assessment of the potential consequences of not addressing technical debt, including the effects on performance, maintainability, or scalability._  

**Location**  

> _The exact location of the affected code, file, and line number._  

**Priority**  

> _A prioritization (critical, high, medium, low) of technical debt based on its impact and urgency._  

**Estimated effort**  

> _An estimate of the effort in time and resources required to resolve the technical debt._  

**Resolution Plan**  

> _The plan to address technical debt, including next steps, dependencies, and any approvals or resources required._

github-technical-debt-issue-template

Note that some fields are omitted in the template:

  • owner: The GitHub platform natively provides this field.
  • date incurred: You can use the creation date as the incurred date.
  • status: GitHub projects provide the ability to create custom fields, such as "status", to easily track the technical debt state without explicitly adding the field to the record.

Alternatively, we can use markdown notes for your technical debt records, for example using:

I'm using the following template along a small script in Obsidian to track the technical debt in my personal projects:

---
id: <%task-id%>
aliases:
  - <%task-id%> <%title%>
tags:
  - task
  - technical-debt
created: <%timestamp%>
status: <%status%>
priority: <%priority%>

---

# <%task-id%> <%title%>

## Reason 

## Impact

## Location

## Estimated Effort

## Resolution Plan

Other automated tools can track some of the technical debt of our project. Check Source Code Analysis Tools to know more about how to choose a tool.

Prioritizing Technical Debt

We can use some of the broadly known frameworks like:

Conclusion

Maintaining technical debt records changes the way we manage the technical debt of our projects. It's not just about keeping track of problems; It's about encouraging a proactive approach to software development. By documenting and prioritizing technical debt, we can address challenges early on, preventing them from becoming bigger problems in the future.

I have found that having clear records allows us to make informed decisions about where and when to allocate resources and how to optimize the development effort. Technical Debt Records serve as a learning tool, providing us with valuable information about patterns of shortcuts or recurring problems that can be addressed through better design or refactoring.

At its core, adopting technical debt records is not just a practice: it is a mindset shift toward building robust, scalable software. It allows us to deliver better outcomes for our users and stakeholders while fostering a more collaborative and proactive team environment.

So, please start documenting your technical debt today, your future self will thank you.

Related Links

  • https://www.agilealliance.org/project-management-and-technical-debt/
  • https://www.atlassian.com/agile/software-development/technical-debt

Previous Post