DEV Community

Cover image for How to manage Technical Debt
Aleksey Pastuhov
Aleksey Pastuhov

Posted on

How to manage Technical Debt

Originally posted on my blog

Today more people think about technical debt than 5 years ago. Because every project has a debt, but not everyone drives it. And even if they drive - they will just keep a snowball in most cases.

I want to share how I prefer to manage technical debt and what it gives to me in a result.

Definition and the problem

What Wikipedia tells us:

Technical debt (also known as design debt or code debt) is a concept in software development that reflects the implied cost of additional rework caused by choosing an easy solution now instead of using a better approach that would take longer.

If technical debt is not repaid, it can accumulate ‘interest’, making it harder to implement changes later on. Unaddressed technical debt increases software entropy.

In easy words, technical debt means a list of invalid solutions, which you or your team made by mistake. Do not forget - everyone can be wrong. So if you do not manage your debt - you will get the next list of problems.

  • Demotivated team
  • Have no ability to control project risks
  • Increased software entropy
  • Everyone would like to rewrite the whole project from scratch


List of causes can be very big, but I defined the most popular from my point of view.

  • Requirements are still being defined during development
  • Development starts before any design takes place
  • Business pressure
  • Lack of process or knowledge
  • Last minute specification changes
  • Poor technological leadership
  • Lack of collaboration
  • Outdated technologies
  • Bad development practices

You noted that most of those causes related to a business or a client. And this is true - in most cases, technical debt is filled-up in collaboration with your manager. You should hear the next phrase.

Do it now because we really need.

And then you come to some compromise via increasing of your technical debt.

Disclaimer: At the end of the article you will find a link to the full list of root causes.

Technical debt and PoC

If you work on a Proof of Concept, do not worry about technical debt. Because someone will replace PoC with the more stable solution. The issue that everyone on a project should be on a same page.

Popular solution

In most cases, developers think it is enough to write TODO item in their code. But imagine if you have 40 repositories for micro-services on a big enterprise. How will you collect all TODO-s? Scan the sources? Okay, but how will you track progress? If you do not see how much you have done - you do not feel happy.

Here I would like to lead to my way of technical debt management.

More precise solution

I propose to use the next structure as a table. You can extend the structure with additional columns, but please - do not shrink.

  • Number
  • Issue
  • Cause
  • Solution
  • How to prevent?
  • Initiated
  • Solved
  • Status
  • Assignee

Seems big, but let me dive in and describe every point in details. Except for Number - an auto-incremental stuff.

Issue - Cause - Solution - Prevention

The issue used for code-name, which will help you find and identify an item. But any issue has a root cause, and it is critical to define the cause.

When you fill the Cause column answer next questions: Why/How/When an issue occurred? Questions will help you define a root cause and understand who made a mistake and why.

When you know the root cause - you can fix an issue. And it is the best time to describe your solution. You can brainstorm with a team and write the solution, so everyone will be on the same page.

And do not forget - in future you need to prevent that issue. If you have the same issue over 3 times - you have a problem in your development process and something is going wrong.

Initiated vs Solved

Initiated means that you found or created an issue in some period. You can write the date, but I prefer to write the number of a Sprint or Iteration. In a such way, you can analyze a table and see a correlation between rush-sprint and increased technical debt.

And also do not forget to write when you solved an issue. If you do things right - you can build such chart.

Resolution chart

You can use resolution chart to define when you made a lot of invalid descisions. Also, you can find out that you forgot to fix debt for a long time. Non-stacked area chart is best for that case. For vertical axis - use amount of total/resolved issues per sprint or date.

Status and Assignee

You can use Jira or any other task tracking system or do not use it at all. But please - do not remove a completed item from the table. Otherwise - you will not be able to track a progress and amount of completed stuff. Also do not forget that you wrote how to prevent that issue in future.

Example of an item

Here I provide an example of an item in technical debt.

Column Value
Number 13
Issue Outdated README file
Cause After creation of landing page, there were changes in a folder structure
Solution Update the file
How to prevent? Update the README file right with changes in structure in the same Pull Request
Initiated 21
Solved 25
Status DONE
Assignee Aleksey Pastuhov

Here I want to note that you can fix an issue in time, it is simple prioritization.


Remember that you should monitor your debt iteratively, and take tasks into your sprints to get things done.

This is how I prefer to keep and manage technical debt. If you do right, you will have positive results:

  • A motivated team
  • You will be able to control technical risks
  • If there are no requirements or design - you have a lot of stuff to do
  • And you will be able to debate to your manager or a client that you need a sprint for code stabilization

Share your feedback and let me know how you used to manage technical debt.
Send me a message or tweet!

P.S.: Do not forget about prioritization! Just add “Priority” column, if it's required in your case.

Originally posted on my blog

Useful links

Top comments (5)

fpuffer profile image
Frank Puffer

Basically this is issue tracking for technical debt. Shouldn't we track technical debt issues together with all other issue, say features, bugs and change requests?

apastuhov profile image
Aleksey Pastuhov

Nice point, and you are partially right. As I wrote in the article:

You can use Jira or any other task tracking system or do not use it at all.

The idea of having such table is to focus on causes and ways to prevent an issue.

When we look at the debt as a simple technical task - we do not think why it happened. Also, you lose an ability to review your technical debt from a helicopter view.

But still - you are free to use any task tracking tool to track the progress of a single task.

fpuffer profile image
Frank Puffer • Edited

I understand. My point is that all development processes I know are based on tasks. A developer is not supposed to do (or at least isn't paid for doing) anything outside a task. So to make the reduction of technical debt happen, you need to define tasks for it in the standard tracking system as well.

Thread Thread
apastuhov profile image
Aleksey Pastuhov

Yes, you need and you need to plan it as a part of the sprint/milestone/etc.

A developer is not supposed to do (or at least isn't paid for doing) anything outside a task.

In my honest opinion, it is a bad practice from evolution/growth perspective.

Thread Thread
fpuffer profile image
Frank Puffer

In my honest opinion, it is a bad practice from evolution/growth perspective.

Not neccessarily if a developer can create additional tasks without too much bureaucratic overhead.