How much technical debt do you own?

Identify and catalog your technical debt

2022, Feb 01

What is technical debt?

Ward Cunningham first mentioned the technical debt (TD) metaphor in 1992 [Cunningham, 1992]. His definition, “not-quite-right code,” remains the most commonly cited. Still, it has been extended to refer to those internal software development tasks chosen to be delayed, but that run a risk of causing future problems if not done eventually. Thus, it describes the debt that the development team incurs when it opts for an easy or quick approach to implement in the short term, but with a greater possibility of a negative long-term impact.

Debt can refer to any aspect of the software that we know is inappropriate but do not have time to fix at the moment, such as outdated/missing documentation, planned testing that is not executed, overly complex code that needs to be restructured or refactored, and known defects that remain uncorrected. These immature artifacts result in unexpected delays in carrying out necessary modifications and difficulties meeting the project’s established quality criteria [Spínola et al., 2013] [Zazworka et al., 2013].

Technical debt mapping steps

1. Identify your major areas, components, or features
2. Prioritize them. One advice is to follow the product roadmap to take advantage of work already planned in the same area (or get it ready for changes).
3. Identify the SMEs (subject matter experts). The SMEs are usually people who have worked on that area, component, or feature, in the past. You will need SMEs from different roles (developer, architect, designer, UX expert, QA engineer, etc.) because technical debt is not only on code. You will understand it better with the guidelines section.
   Also, it is important that while the SMEs may be the ones responsible for technical debt identification the team responsible for paying it always has the last word in terms of defining the solution and the estimates.
4. Schedule time. This time is essential, and it needs to be planned and negotiated. As the SMEs follow the guidelines, they will spend time otherwise away from their regular tasks. Ideally, work with different roles separately but group the SMEs from the same role for each component. They will help each other and be more effective.
5. Document it! A ticket in your issue tracker is not enough if you don’t actually gather the information needed to make decisions around payment and prioritization.

Documenting technical debt

The most common TD template is this one, adopted by Zazworka et al., 2013 and Spínola et al., 2019:

According to these papers, you will want to start with:

1. Low principal, high interest, and high interest probability
2. Low principal, medium interest, and medium or high probability;
   Low principal, medium or high interest, and medium probability.
3. High estimated principal with low interest and low probability might not pay off. You may want to delay paying these.

Technical debt identification guidelines

There are currently around 15 different technical debt types identified in the literature¹², and among them, the most common according to Berenguer et al., 2013 are:

Distribution of TD on a typical product

I’ve copied the descriptions of each, but I added a few questions to help the SMEs identify each type of TD.

Design debt (21.99%) refers to violations of good design principles and practices. This type of debt can be discovered by analyzing the source code. For example, using code review techniques or static code analysis tools.

Relevant questions:

• Which areas are more defective-prone?
• Which areas of the code are harder to understand or explain?
• Where are the code smells?

Test debt (19.94%) refers to any issues regarding testing activities. For example, planned testing that was not conducted or low-test coverage.

Relevant questions:

• Which areas should have more UI-level tests according to the team’s QA strategy?
• Which manual tests should be automated according to the team’s QA strategy?
• Which areas should have more integration and unit tests according to the team’s QA strategy?

Code debt (14.66%) refers to problems found in the source code that negatively affects readability and maintainability of the code—for example, too complex methods or non-existing coding standards. To remove code debt, code refactoring is needed.

Relevant questions:

• Which areas should have more UI-level tests?
• If you had a week to improve some part of the code, which one would you choose?
• Which manual tests should be automated?
• Which areas should have more integration and unit tests?

Architecture debt (10.70%) refers to issues and problems with the system’s architecture that affect the architectural requirements (e.g., performance, maintainability, robustness, etc.). For example, violation of the modularity principle or poor separation of concerns leads to significant evolution, maintenance, and system extensions problems.

Relevant questions:

• Where does the application not abide by the latest architectural decisions (such as adopting micro frontend, etc.)?
• Where are known performance issues?

Documentation debt (9.09%) refers to any issues and problems discovered in the documentation of the software project, including missing documentation. It is discovered by looking for inconsistent, missing, inadequate, or incomplete documentation. For example, technical documentation is outdated, not reflecting the actual state of the system.

Relevant questions:

• Which technical documentation is missing?
• Which documentation is outdated? Is it no longer needed or needs to be updated?

Requirements debt (8.80%) refers to the trade-off between agreed requirements and requirements that are actually implemented in a software product. For example, this can be manifested as partially implemented requirements or implemented only for some cases.

Relevant questions:

• Which business/product documentation is missing?
• Which business/product documentation is outdated or incomplete?

Process debt (4.11%) refers to inefficient processes. For example, a process changes over time, and the existing practices are no longer efficient.

Relevant questions:

• What activities are mechanical or repetitive?
• Which activities do you feel don’t add (enough) value for the effort required to execute?
• Where are the bottlenecks? What are you constantly waiting for?

Infrastructure debt (2.93%) refers to issues that significantly reduce the teams’ ability to deliver quality products in an organization, such as using outdated tools or postponing regular software or system updates.

Relevant questions:

• What is supported by technologies (tools, libraries, frameworks) we have decided to move away from (or is on an old version)?
• Which technologies should we move away from or update?
• Which environments and branching strategies should we be adopting?

Defect debt (2.79%) refers to known defects discovered by testing activities. However, the corrective actions are postponed or never implemented. Decisions to delay the corrective actions can accumulate a significant amount of TD in the system.

Relevant questions:

• Which are the older known defects still open?
• How many defects are currently open?

What’s next?

If you have been accumulating technical debt, I suggest you take a close look at what you currently have and talk to the engineers to start getting the situation under control.

Meanwhile, a change in posture will definitely help you stop accumulating technical debt without need. It is totally up to you:

If you think this post is helpful, sound off in the comments!

Cheers!

If you like this post, please share it (you can use the buttons in the end of this post). It will help me a lot and keep me motivated to write more. Also, subscribe to get notified of new posts when they come out.

 Back