Navigating Technical Debt: How to Identify, Measure, and Manage it

What is technical debt?

Imagine you're building a LEGO castle. You're in a hurry, so you start using pieces that don't fit together quite right. The castle looks fine from a distance, but up close, you can see the mismatched parts.

In software development, technical debt is like those mismatched pieces. They can lead to increased maintenance times, bugs, and difficulty in adding new features or scaling.

Ward Cunningham, a renowned software developer and one of the creators of the Agile Manifesto, coined the term technical debt in 1992, with the premise that taking shortcuts in software development allows for faster initial delivery but entails “interest” in the form of future cleanup.

Paying off technical debt means taking the time to go back and replace those pieces with well-thought-out, robust solutions that align with the overall design. It's an investment that ensures that software is maintainable, scalable, and performs well for the long run.

TL;DR

Technical debt happens when shortcuts in software development make systems harder to maintain, scale, and improve. Measuring technical debt is a recognized industry challenge, and no single metric can reliably capture it. To manage it effectively:

• Identify it across four key areas: code quality, CI/CD pipeline issues, documentation and knowledge gaps, and stalled migrations

• Measure it through team-led assessments, not automated metrics alone

• Prioritize it based on what directly impacts productivity, scalability, and customer experience

• Don't overlook organizational debt, he people-side shortcuts that compound alongside your code

Measuring to improve

At AppDirect, we believe in driving continuous improvement based on what we can measure. But how can we measure technical debt?

It turns out that measuring the level of technical debt in a system is a recognized problem in the software industry. Recently researchers at Google attempted to correlate technical debt as understood by different engineering teams with 116 existing metrics that measure codebases.

"The results were disappointing, to say the least. No single metric predicted reports of technical debt from engineers; our linear regression models predicted less than 1% of the variance in survey responses."

They found that over time, these measurement techniques didn't correlate with team member estimates of technical debt. Their conclusion was that existing software engineering metrics can't be used to accurately measure technical debt. New ways of measurement are needed.

We love hard problems

A conclusion like this is exciting because this represents a widespread, unsolved problem in the software engineering industry.

One reason that measuring technical debt is so difficult is that the ideal state of a software project is held in the minds of the team that maintains it. What measurements other than an opinion survey can look into the team's imagination?The question we're asking is, what impedes our forward progress? What could be better?

For this reason, it's the responsibility of each team to assess and document their own level of technical debt as part of their understanding of platform resilience. Not all technical debt needs to be resolved. It's important to focus on technical debt that directly impacts a team's productive work.

Types of technical debt

Let's examine the different kinds of technical debt to consider how they apply to engineering strategy. Consider four major categories of tech debt.

Codebase challenges

Challenges with the codebase are the most obvious kind of technical debt. Problems that accumulate here correspond to issues with other engineering processes. That's the nature of debt -- it accumulates. So proactive processes around refactoring during routine development are essential to prevent larger problems down the road.

"We can fix it later," we say, but later never comes. This becomes a migration challenge.

Code quality

In this case, product architecture or code within a project was not well designed. It may have been rushed, or was a demo that became a production system. In the interests of time to market, a team is racing ahead to build features needed for product/market fit.

"We can fix it later," we say, but later never comes. This becomes a migration challenge, discussed below.

While this might be okay as long as the software is delivering value for the business, these poor architecture choices or outdated code standards may lead to maintainability issues. Refactoring and adherence to design principles are key.

Dead and/or abandoned code

In this case, code, features, or projects were replaced but not removed. This reflects a lack of proper code maintenance and clean-up. Regular audits can mitigate this issue.

Dependencies

Modern software uses an ever-growing list of dependencies. These need to be kept up to date, and sometimes dependencies can be unstable, rapidly changing, or trigger rollbacks. Problems here highlight the need for strategic management and version control.

To address issues with dependencies, sometimes teams decide to move an implementation from one dependency to another, triggering another migration.

Pipeline and process challenges

Very closely related to codebase issues are challenges around the pipeline for testing and releasing the codebase. Investments made in seed data, unit, and integration tests act as technical assets that can help prevent the accumulation of debt.

Testing issues

Poor test quality or coverage, such as missing tests or poor test data, results in fragility, flaky tests, or lots of rollbacks. This reveals the necessity for robust testing, which strengthens the product and minimizes post-deployment issues.

Automated tests provide confidence for frequent, rapid delivery. If tests cannot be trusted, cycle times stretch out.

Release process issues

The ability to deploy faster helps solve many problems in software development. To enable this, the rollout and monitoring of production needs to be updated, migrated, or maintained. A need for an updated release process reveals the importance of deployment planning and monitoring in maintaining product quality.

Large charges to the build, testing, or deployment pipeline can require switching from one technology to another. These are complex migrations that need to be managed carefully.

At AppDirect, we have seen significant changes to our release process when we moved from a weekly release of a monolithic application to on-demand deployment of smaller services. With improved testing automated into our release process, we can deploy hundreds of times per day.

Knowledge challenges

As time passes at a startup, information about how a project works is hard to find, missing, incomplete.

In this era of doing more with less, we're faced with more challenges around knowledge management. Simultaneously, we have more tools than ever to help address them.

Documentation gaps

As time passes at a startup, information about how a project works is hard to find, missing, incomplete. This may include documentation on APIs or inherited code. It can also include documentation about functionality and how features are intended to be used or supposed to work. A lack of clear information can slow down development and increase mistakes, underlining the need for comprehensive documentation practices.

At AppDirect, we've continued to invest in tools to improve access to documentation such as our own internal Knowledge Center drawn from code and documentation committed to repositories and custom Udemy Business courses.

More recently we've built tools that leverage AI and large language models to consolidate information scattered across the enterprise. You can then ask your technical questions chat-GPT style. Now powered by our own Devs.ai, both interactive questions and answers as well as autonomous code review agents are available for both internal and external customers.

As clever as AI tools can be, if they're reading artifacts of the software development process like Jira tickets and pull requests, getting the best results from these tools requires teammates to create high quality documentation. Text documents, such as markdown stored with code repositories, work best because it's easier to update together. The first answer to learning something can't be to jump on a call, watch a video, or find a slide presentation.

The team lacks necessary expertise

This may be due to staffing gaps and turnover or inherited orphaned code/projects. A lack of skilled resources can lead to inefficiencies and reduced quality, emphasizing the need for ongoing training and proper hiring strategies.

Migration challenges

These may be motivated by the need to scale, due to mandates, to reduce dependencies, or to avoid deprecated technology. In the Google study referenced above, 20% of the technical debt types were identified as migration issues.

As we've seen, significant challenges in every other category of technical debt result in migrations. In effect, paying down technical debt itself is a migration. If not managed well, these migrations themselves become a form of technical debt.

Migrations are projects, and while there are challenges in measuring other kinds of technical debt, there are a lot of measurements and strategies we can deploy around project management.

Migration is needed, planned, or ongoing

At AppDirect, our engineering team has global initiatives that require large migrations, such as moving from RabbitMQ to Kafka. This requires special coordination between teams to address properly, because migrations like this involve message services with producers and consumers in different teams. These kinds of changes are internal to the engineering function and need to be planned and completed.

Some migrations are initiated by our enablement teams. These teams create and operate services used by every engineering team for the organization, such as the cloud platform, and the data platform. They're migrating to new technologies that the rest of the organization can then adopt.

There are also migrations that are specific to the individual teams working on parts of the value stream. As these teams build new capabilities for the business, migrating away from existing functionality must be planned out. How customers are impacted is a big part of this.

A whopper of a migration is something like moving from a monolith to microservices, which many companies have struggled with. In migrations like this functionality is typically extracted in different ways. Extraction by reimplementation remains the slowest, most comprehensive way to decompose a monolith. Often this method of extraction is coupled to a rewrite story, which offers its own challenges.

The migration was poorly executed or abandoned

Sometimes, a migration that's in progress might become overlooked, either due to shifting company priorities, staffing changes, lack of documentation, or some other reason. When migrations of any nature are not well managed, they can become abandoned.

This can make an already complex system a lot more complex, especially if it happens a lot. The system can become more difficult to support and maintain because of the many different code paths caused by the combinatorial explosion of complexity.

It's incredibly important to make sure that the team minimizes the amount of time that multiple versions of the same functionality need to be supported in production.

As we've seen, while there are four major categories of technical debt, migrations are a special category. Large challenges from the other areas eventually become migrations when we prioritize them.

Prioritizing technical debt

I urge all engineering teams to incorporate the prioritization of and reduction in technical debt into their day-to-day work. This commitment requires:

• Regular assessment: Continuously evaluate areas of potential debt and align them with business goals and customer needs within each technical domain, and in the interface points between domains.

• Measure and quantify: Develop techniques to quantify the results of your assessments so that you can track progress over time.

• Strategic planning: Build clear plans for tackling existing debt, considering both immediate needs and long-term scalability. Plan for debt reduction as part of building new capabilities.

• Ongoing education: Foster a culture of learning and collaboration, where understanding technical debt is a shared responsibility. This isn't merely the responsibility of a few, it's shared by all.

• Alignment with business objectives: Ensure that actions to reduce technical debt align with overall business strategies and contribute to a seamless customer experience. Just as not all debt is bad, not all technical debt needs to be addressed.

By embracing these principles, at AppDirect we're not just building the #1 subscription commerce platform; we're crafting resilient, efficient systems that can adapt and thrive.

Technical debt’s twin

Every engineering leader understands technical debt. The shortcuts in code, the migrations that stalled, the tests that never got written. We have frameworks for it, we budget for it, and we talk about it in every planning cycle.

But there’s a twin that lives in the org chart, and it’s at least as dangerous. I call it organizational debt.

Organizational debt accumulates when the people side of an engineering organization evolves through expedience rather than design. It’s the structural compromises you make, reasonable in the moment, that quietly compound until they constrain everything you’re trying to do.

If technical debt is the mismatched LEGO pieces in your castle, organizational debt is something else entirely. It’s building that castle with a crew where only one person understands how the drawbridge works, half the team is on loan, and the blueprints exist only in someone’s head.

Technical debt and organizational debt are not just analogous—they're interconnected.

Technical debt often causes organizational debt. When a system is poorly documented, whoever understands it becomes a SPOF. When a migration stalls, the team structure built around the old system persists. When contractors are brought in to handle a backlog of technical debt, they become a dependency.

And organizational debt causes technical debt. When knowledge is concentrated, code reviews suffer. When team structures don't align with system boundaries, ownership gets muddy and quality degrades. When acquired teams aren't integrated, architectural standards diverge.

The most effective engineering leaders I know manage both simultaneously. They see the org chart and the architecture diagram as two views of the same system.

Read the full article on organizational debt, What’s Slowing Your Engineering Organization Down.

Your turn: How are you tackling technical debt?

If you look at your own organization, where is the technical debt concentrated?

We've explored the complexities and challenges of identifying and managing technical debt. Now, I'd love to hear from you. How is your organization prioritizing and tackling technical debt? Are you using specific metrics or methodologies that you've found effective? Share your insights and strategies in the comments below. Together, let's build a more resilient and efficient software engineering culture.

Join the conversation on Mathew’s original LinkedIn article.

Mathew Spolin leads global engineering at AppDirect, where managing organizational debt across multiple countries, acquisitions, and restructurings has been as critical as managing our technical debt. If this framework resonates, I'd love to hear your examples.