The Engineer's Guide to Creating a Technical Debt Proposal

Technical debt is a slow killer of an engineering team’s productivity. At first, technical debt might not seem to be a blocker, but it can hinder your team’s efficiency as time progresses.

In many cases, teams reach a tipping point where technical debt becomes a blocker for making any progress in terms of implementing new features.

This article helps you craft a technical debt proposal to justify the time spent solving and, more importantly, prevent technical debt. Let’s look at what elements you should include in a technical debt proposal to help your management make a decision.

First of all, let’s explore why you need to write a technical debt proposal?

Why do you need to write a technical debt proposal?

A technical debt proposal allows you to justify the time and resources spent resolving technical debt and creating a plan to further prevent tech debt.

Your management might be unaware of the technical issues that are slowing down your Engineering team.

Hence, you need to gather the evidence, propose a plan and metrics to measure success.

It’s possible you made an incorrect estimation, and a solution turns out not to work. Therefore, you want to be able to track the effectiveness of your technical debt proposal to be able to intervene when it doesn’t work out as expected.

The rest of this article will guide you through the different steps you can follow to create a technical debt proposal. The below plan focuses on identifying tooling and how you can build your plan around this tooling.

Step 1: Identify issues with the biggest impact on tech debt

To get started, identify tech debt issues that have the biggest impact on your engineering team’s productivity. Engineering teams are often aware of these issues as they linger around in issue tracking or project management tooling.

The best way to identify these issues is to start tracking technical debt in your editor. Tracking technical debt in the editor allows engineers to get full visibility on technical debt, see the context for each codebase issue, and reduce context switching.

The best way to identify technical debt is to use free Stepsize extensions for VSCode or JetBrains that integrate with Jira, Linear, Asana, and other project management tools. It’s a quick way to get started and collect all the key technical issues in your codebase. 

Step 2: Identify tooling

Don’t underestimate the power of proposing proper tooling to manage tech debt. Some engineering teams might not be using any tooling, while other companies are not using the correct tooling or use outdated tooling. These scenarios are plausible and need to be considered when identifying tooling to be included in your tech debt proposal.

For many teams, implementing correct tooling can resolve and prevent a lot of technical debt. However, engineering teams need to justify the costs of using particular tooling.

You need to ask yourself the following questions when selecting tooling:

1. Which tool offers the best capabilities to address your team’s issues?
2. What are the implications of implementing a particular tool? Some tools require a particular setup your engineering team might not be ready for, or a tool requires self-hosting, including additional costs.
3. What’s the tooling cost, and are there cheaper options available that can address your tech debt issues?

Once you think you’ve found the proper tooling, make sure to include a summary of the above questions in your tech debt proposal. This summary will help a CTO, team lead, or management better understand why you’ve selected a specific tool.

There are plenty of tools to help you deal with technical debt.

Here are some of the examples of these tools.

A continuous integration (CI) tool can help a team guarantee the quality of their code. Expanding on this, a CI tool can enforce coding standards and perform complex types of testing, such as integration or end-to-end testing, to provide developer teams with trust in their code.​​Static analyser tools such as SonarQube are used to analyse source code in search of technical debt.These tools use quantitative data to help developers identify hotspots in the codebase likely to have technical debt. 

One of their limitations is that they won't help you identify medium to large pieces of debt that span multiple parts of your codebase, and won't provide you with the context necessary for you to truly understand each piece of debt and how to prioritise and ultimately tackle it.

Frontend to issue tracker tools like Stepsize helps Engineering teams track technical debt in the editor and link issues to code.

It would be the best choice for you if you want to:

Track and fix technical debt continuously Improve your coding standardsDecrease context switching by creating issues in the editor

Step 3: Set metrics and define your baseline

Next, you need to define metrics to justify the costs. Metrics allow you to measure the effectiveness of your tech debt proposal, and especially the effectiveness of the tooling you’ve selected. 

For instance, the tooling you’ve selected does not resolve your issues based on the metrics you’re measuring. It allows you to intervene and readjust your tech debt proposal or look for different tooling to address your issues. 

In other words, having metrics can potentially save you a lot of wasted money on incorrect tooling. On top of that, adding incorrect tooling can further increase tech debt because your engineers have to learn a new tool they are not familiar with.

Here’s a quick list of metrics you can define for the continuous integration example.

Test coverage percentageNumber of issues related to coding standardsNumber of bugs discovered in productionFeature throughput of a software engineering teamMean time to repair a bug

Tip: Don’t forget to set your baseline. Without a baseline, it won’t be possible to determine the effectiveness of your tech debt proposal. Therefore, only measure metrics for which you’ve data available. 

Step 4: Look at other ways to solve technical debt

While tooling can quickly resolve technical debt, look at other ways to resolve technical debt. 

Often, you can combine a proposal to implement new tooling with other initiatives like a refactoring week or implementing a new type of meeting, such as a retrospective meeting. 

A refactoring week gives your team the needed breathing room to reassess the codebase and identify key issues that they want to address. Besides that, it can serve as a reset, implementing new tooling to reduce the team’s technical debt further.

Other potential initiatives are educational sessions where team members share knowledge about the codebase or educate other team members about new technology. It all depends on the types of technical debt your team experiences. 

Conclusion: Stay alert!

Once your team has resolved technical debt, don’t let technical debt creep up on you again.

Therefore, continue measuring the metrics you’ve set out. Besides that, you can create a plan to measure additional metrics to better understand your team’s performance and how technical debt builds up. 

In short, technical debt is an annoying monster that can quickly return. Stay alert!