How to track and prioritize technical debt

2. Risk to future projects

Sometimes, a new feature is incompatible with existing code – whether that be it’s entirely blocking implementation, or making its cost prohibitively high. Tech debt makes this more likely.

Tech debt has a tangible effect on your product and code base – and what can be added to it.

By tracking where your tech debt lives, it means you have a chance to spot such issues during the planning phase, not development. It also allows you to prioritize tech debt repayments and incorporate the debt work as part of the project – reducing the risk of surprise roadblocks or schedule delays during development.

Rich text editor example of prioritizing tech debt

As an example, TinyMCE’s Enhanced Image Editing plugin carried a lot of technical debt, until it became so bad that updates were impossible without a major rework.

Debt accrual:

Over time (due to repeatedly tight deadlines), the Enhanced Image Editing’s unique UI elements, like its crop frame, were hacked into the TinyMCE Core, instead of being implemented properly. Over time, other changes complicated these hacks until any further major changes to the plugin were impossible without significant refactoring.

Debt repayments:

Luckily, this was known tech debt. When roadmap discussions turned to improving the Enhanced Image Editing plugin, Tiny was able to prioritize and schedule repaying the tech debt ahead of other big projects. Otherwise, it may have delayed or even blocked any such project – especially since it was a big project with specific release conditions.

Be careful, though – understanding the impact of tech debt isn’t always that simple.

All these problems can be avoided, or at least managed, as long as you track tech debt in your product. So now let’s look at how to do that.

How to track tech debt

No matter whether you intentionally choose to take on a piece of tech debt, or your team stumbles on old tech debt accidentally: Don’t let it become invisible.

Write it down (or notate it in some way) so that next time development velocity dips, or a project is delayed, or you’re considering a new feature, you have a list you can check for potentially-related tech debt.

The exact notes you make may depend on your prioritization framework (more on that in a moment). However, a few examples are:

- What is the scope of the tech debt?

What areas of the product does it touch?

What side-effects will it have?

When might it cause problems in the future?

A dependency tree can be great for figuring this out, especially in a rich text editor.

- What is the principal cost of repaying the tech debt?

If your team were to fix it then and there, how long would it take them?

Do they think that estimate might increase or decrease over time?

- Are there any caveats to repaying it?

Does it require domain knowledge that only certain people have?

Does it require input from other teams?

Are there deadlines for repaying it?

- What is the ongoing interest cost of leaving it?

Who does it affect?

How often will that interest be incurred?

What will that cost you?

Once you have that information, you need to compile it somewhere.

The best place for tech debt is alongside other work – in your task backlog, your roadmap, or next to other planning documents.

You need to be able to prioritize it in the same way you prioritize other work, and that means:

• Record it in the same format.
• Use the same prioritization framework.

Otherwise, the differences might complicate the process, and that could lead to it not being prioritized at all. Of course, a big part of how you manage tech debt is the tools you use to track it.

1. Project management and issue tracking tools for tech debt

Issue trackers like Jira, Azure Boards and GitHub Issues can be good for tracking tech debt (Jira even has a few articles on it). Alternatively, tools like ProductBoard can help you track tech debt at a higher level.

If you’re already using one of these tools, that’s great! Adding tech debt will make it easier to see the bigger picture, to do comparative analysis, and to prioritize tech debt against and with other work. Or… if you want something specifically designed to track tech debt, try Stepsize, which also integrates with various IDEs and issue tracking tools.

Alternatively, if your use case has specific needs, you may need something a bit more custom.

3. Automated code analysis tools for tech debt

Unfortunately, you can’t totally automate tech debt tracking. However, code analysis tools can often detect outdated code and dependencies, potential security vulnerabilities, and bad programming practices – which is a good start.

Make sure to research what the tool can and can’t do though, and how well it aligns with your use case. These tools can be indispensable when used correctly, but can be more trouble than they're worth if there’s misalignment.

The OWASP Foundation has a great guide to code analysis tools – including a selection criteria for choosing a tool. If you want a shorter list, try searching for “code analysis tool” plus the language(s) that your product is written in.

However, code analysis tools can only find some forms of tech debt. Even if you do use one, you’ll still need another tool to track the other types of tech debt, so you can prioritize it all.

However, beware simple frameworks and their inability to capture the full picture.

Although the “Reach” in RICE usually refers to the number of people impacted, with tech debt you may want to consider the reach of a piece of tech debt within the code base. Within a rich text editor, this is where a deep understanding of the architecture and dependencies helps you prioritize.

For example, in a rich text editor, selection bugs tend to be high effort, but their side-effects can impact a significant portion of the editor. Because of this, you may want to consider the reach (portion of product affected) and impact (how bad are the side effects) in order to properly calculate what the ongoing costs of the tech debt are.

In addition, you need to remember that as priorities change, so can impact – especially if a piece of tech debt affects an upcoming roadmap item. And, changes to a code base over time, can change the principal effort too – like the Enhanced Image Editing plugin (see section 2. Risk to future projects) which became increasingly more complicated with each additional hack.

That’s why it’s important to regularly review and re-evaluate your tech debt, especially in light of changes made and the changes coming, in order to properly manage tech debt in your product.

What if tech debt gets unmanageable?

Ideally, you’d want to pay down your tech debt over time, in nice little manageable chunks and never have any issues. But that’s not always how it works.

Sometimes rewrites/refactorings are necessary

Sometimes, a piece of tech debt can become so big and so costly, you just have to bite the bullet and do whatever it takes to fix it.

You have to sit down with your team, and figure out what it takes to pay down the principal and get rid of the debt once and for all. It may end up being a big project – the longer it's been there and the bigger the codebase, the more likely it will snowball.

However, when leaving it causes constant drain on developer efficiency, or repeated unsatisfied customers, or even the complete obstruction of new features, the long-term returns are worth the effort.

Sometimes you can make it someone else’s problem

Alternatively, sometimes you can hand the problem off to someone else.

The software ecosystem is constantly evolving, with new libraries and tools released every day. Just because you had to write custom code for something when it was first implemented, doesn’t always mean you have to keep maintaining that code.

Remember to shop around to see if there’s anything you could use instead. It might still require some work to switch over and set up, but long term it means less code to maintain, less tech debt to track, and less problems overall.

And, if you’re looking for a rich text editor, well there’s a really great one…