loading...
Cover image for Communicating Technical Debt

Communicating Technical Debt

integerman profile image Matt Eland ・10 min read

Many developers feel that product management and executive leadership don't "get it" when we talk about technical debt. At the same time, if you ask developers about factors vital to the long-term success of a project, paying down technical debt is high on the list. So, how can we communicate technical debt in a way that bridges that gap?

As a development manager, a core part of my job is to act as a bridge between product management and development teams. Let me share with you what's worked well for me so far.

This post is inspired, in part, by bob.js' wonderful article on Accounting for Technical Debt and is intended as a bit of a companion for that article.

Defining Technical Debt

Let's start from Webster's definition of debt:

Debt: a state of being under obligation to pay or repay someone or something in return for something received : a state of owing

In this context, we incur technical debt by taking temporary advantage of something while incurring an obligation to pay it back.

Principle and Interest in Technical Debt

Extending further, we pay additional interest for our debt over time, meaning that a small piece of technical debt becomes larger over time.

As an example, if we cut some corners in implementing a feature by duplicating a method and making slight modifications, we pay interest on that decision every time we need to make a change that should modify both methods.

Even if only one method is actually modified, the failure to modify the duplicated method likely constitutes a bug, introducing a form of quality debt into the application in the form of a hidden bug waiting to be encountered.

In this example, the principle of the technical debt is the time saved during initial implementation while the interest is the additional time, quality, and risk costs incurred for that decision until the point that it is resolved.

I particularly like the financial analogy when talking about technical debt because it takes something hidden and unknown to business-oriented professionals and puts it in terms that they work with on a day to day.

This also highlights that while technical debt can be advantageous in the short term (when interest paid is less than the principle borrowed), it can be ruinous in the long-term.

Penalties for Technical Debt

Above I mentioned the increased amount of development time penalty paid on future items when technical debt is in effect. This is likely the largest form of technical debt that we talk about as developers.

Additionally, we touched on the quality debt that can be incurred by brittle and unmaintainable code, lack of unit tests, and duplication that results in inconsistent behavior when modifying code. This is a form of risk that we pay off as interest when working with tech-debt heavy areas of code.

Another form of interest we pay on technical debt is poor application performance. This is typically paid when technical debt is at the design level as most performance issues ultimately turn out to be poorly designed flows through a system. Yes, you can make tactical improvements to code performance for days and weeks on end, but at a certain point it's hard to get additional improvements until you redesign with performance in mind.

Security vulnerabilities are another form of risk that we can incur as interest on technical debt. Uniquely, though, this does not just manifest itself as code is changed, but the risk starts from the day a vulnerability is present and continues on until it is resolved.

Finally, we do pay a morale penalty to developers when working on substandard code. This is frequently not isolated to just developers, however, as many developers are vocal about the more interesting bits of code they discover and this affects anyone within earshot.

I would further argue that poor code inside of the codebase encourages substandard work on the project because it is shown to be an acceptable level of workmanship, so this form of debt encourages future debt.

Talking to Business about Technical Debt

Okay, so now we've talked about what debt is and the interest we pay until it is resolved, let's talk about communicating these things to business stakeholders.

First of all, product management and business stakeholders are not your adversary. These are your key partners. Any discussion with business on code needs to have trust and respect at its core - from both sides - or friction is guaranteed to occur and success is far less likely.

I would take it a step further and say that establishing a relationship of trust, collaboration, and respect with business partners is even more important to the long term success of a project than technical debt.

In order to have a healthy and productive conversation with business stakeholders, you need to do at least the following things:

  • Come at the conversation looking to improve understanding in both you and them. You want to inform them of current and future obstacles and the prices paid by past decisions and you need to hear and understand their needs.
  • You need to have an extreme amount of professionalism. Developers love to have fun, but when we're alien to the business in our conduct, it's not too hard to see why the business might not think that we're not capable of thinking about the things they think about.
  • Have both data and anecdotal evidence to back up your claims.
  • Have a few key top priority technical debt items already identified.
  • Have flexible plans for resolving things that can be modified by business needs.
  • Have an idea of how long that it will take to resolve things.
  • Have ideas for ensuring that technical debt becomes less of a problem in the future.
  • Be prepared to give progressive status reports as technical debt is paid down.

When talking to business stakeholders about serious levels of technical debt, you are essentially a doctor giving a patient a warning about health complications and future consequences. You need to tell the truth while not being alarmist, and you need to offer a plan to remedy the situation and monitor it going forward.

We'll talk more about these things in a bit.

"Isn't Technical Debt the Developer's Fault?"

I hear this question sometimes from business. It's often not asked in a malicious way and it's even asked reluctantly at times. Most business people don't understand the nature of software development or software projects because they haven't developed code for them. As such, it's completely reasonable to assume that technical debt is the developer's fault.

The truth about this assumption, unfortunately, is that sometimes technical debt is our fault. Sometimes we didn't warn on the consequences of a decision as it was being made, sometimes we didn't notice it until it was too late, and sometimes developers get lazy, make mistakes, or are still growing the full set of skills they need.

However, I choose to believe that the majority of technical debt is not our fault or is detected too late to change without jeopardizing key business goals.

An analogy I like to make when dealing with business stakeholders who blame development for technical debt is one from farming.

In farming, if you repeatedly farm the same land season after season after season, you systematically render that land less fertile and productive by draining the nutrients from the soil. This is why farmers have adopted techniques such as crop rotation (leaving a field fallow or empty in off seasons to recharge) or to substitute soil-enriching crops for soil-depleting crops every so often to help fields recharge.

In this analogy, it makes it clear that while developers are working on what the business wants, project after project, the lack of time available to weed out the fields and allow the metaphorical soil to recharge is ultimately reducing the crop yield. You ultimately don't have bad farmers (developers), but a farming strategy and schedule that optimizes yield for the first few seasons at the expense of long-term viability.

The Business Perspective

Sometimes sacrificing long-term health of a codebase is actually acceptable.

Sometimes you critically need to finish a project to stay in business. Sometimes you plan on completely rewriting an application or retiring it after a number of iterations in favor of a replacement. In this case, productivity in the short run should be the primary concern.

Other times business simply doesn't understand. They live in the world of looking at the needs of stakeholders, sales goals, deals won and lost, contracts at risk, support incidents, bug counts, and other concrete and understandable things and when they hear technical debt, it can be easy to assume it just means "code I'm not particularly fond of" and not "a massive quality risk waiting to unleash a flood of defects on our users".

This is why they need us to translate our day-to-day into something they can understand.

That means we have to look at metrics. Armed with data from issue tracking systems, time tracking systems, source control, code analysis tools, test coverage results, CI/CD pipelines, performance monitoring tools, and other sources you can put together some interesting figures such as:

  • Defects by area of the application
  • Time needed to complete a single feature (particularly over time as this shows losses in productivity)
  • Time spent on development vs support activities
  • % of code that is covered by unit tests over time
  • "code smells" by source file
  • "code smells" over time
  • % of incoming requests that result in errors

Be creative. The exact metrics that are appropriate for your code are going to be unique to your organization and your current flavors of technical debt. If you need ideas on analyzing problems and coming up with ways of representing them, take a look at my post on the 7 basic tools of software quality.

Code Analysis

Code Analysis tools are something I absolutely would lean on. These could be anything from compiler or linter warnings to a dedicated tool that analyzes a codebase and generates recommendations. The exact tools used will vary by the programming language you're using, but I'll share what works well for me.

I use SonarQube / SonarCloud to scan a wide variety of code in many different languages.

Sonar Cloud Issues List

This can also help me prioritize which files need attention most in a very visual manner suitable for communication with business stakeholders:

Sonar Cloud Files by Code Smell

While SonarQube / SonarCloud is good for simple tracking that works well out of the box, more in-depth and customizable analysis may be necessary and should come from a specific tool suited to your programming language.

I use NDepend to analyze .NET assemblies and get detailed metrics and visualizations as to everything wrong with those projects in order to prioritize and track code smells over time.

NDepend Dashboard

NDepend, in particular, can pinpoint methods by size and complexity, code coverage, etc. and generate some very helpful graphs and charts for prioritizing and even potentially communicating technical debt.

NDepend Tree Map

Disclaimer: While I have previously paid for NDepend, my current copy was provided by the developer

Tips for Communicating with Business Stakeholders

So, now that you have the metrics and data you need to prioritize and communicate technical debt, let's talk about that conversation.

First, you need to determine how big of a deal this is. This can range from a 30 second elevator pitch of "We'd really be more productive if we could fix X. Can I send you a short E-Mail with some details and get this included in a future sprint?" to "I've been looking at our code quality and I have some concerns I'd like to share with you. I'd like to set up a meeting for later this week to go over them and talk about some possible solutions. What day would work best for you?"

Second, you need to put together the appropriate level of communication. Typically this is going to be anywhere from a paragraph-long E-Mail to a one or two page report or a 5-10 slide deck. Your goal is to concisely communicate the problem to them in a way that they can understand and participate fairly in a discussion for prioritizing and planning a remedy for the issue.

Thirdly, you need to take their communication styles into account. Some people hate E-Mail or phone. Others hate formal meetings. Style matters too - some people want concise confident statements without any preliminaries while others want to really interact with you and shoot the breeze before getting to business. Some people are motivated by hard facts while others are swayed by stories of how individuals are impacted. Know your audience. When in doubt, try a mixture of approaches or have anecdotes ready to share if your data flops.

I would highly recommend keeping your presentation focused on the bare minimum needed to adequately communicate the problem. Do your homework going into the meeting, but don't bore them. If an executive wants details, they'll ask for it. You're not trying to sound smart or win points here - you're trying to bring a partner into a problem solving world that's not their forte.

Present your proposed plan for remedying things to them as part of the presentation. Expect to be asked questions around how many resources you'll need, how long it will take, what the risks are, and what things the business will be unable to do in the short term due to the loss of resources.

The other thing I would caution against going into these meetings - fair or otherwise - is that many at the executive level are focused on people's clock-in and clock-out times and if you're telling them you need to be able to dedicate time to technical debt and the dev team leaves immediately at closing time every day, shows up late, or takes long lunches, the executives may have trouble focusing on what you're saying - right or wrong, this just tends to be how many people think at that level.

Closing

Now that we know how to communicate technical debt to business stakeholders and, hopefully, get buy in, let's look at some strategies for paying down technical debt.

What's worked for you when talking with business stakeholders? What obstacles have you encountered other than what I've shared above?


Photo by Sabine Peters on Unsplash

Discussion

pic
Editor guide
Collapse
dvddpl profile image
Davide de Paolis

poor code inside of the codebase encourages substandard work on the project because it is shown to be an acceptable level of workmanship, so this form of debt encourages future debt.

Couldn't agree more. Sloppiness - like laziness - is contagious. Like in the broken windows theory. Luckily even the opposite is true, high quality code, highly motivated, driven and positive developers can become the major growth and speed boost for the entire team ( but it is harder. )

the analogy with Farming and rotating the crops is AMAZING.
thanx for the article

Collapse
integerman profile image
Matt Eland Author

No problem! I almost mentioned broken window theory by name, but held off due to length. In the follow-on on paying down technical debt, I'll go into it more.

Collapse
arekx profile image
Aleksandar Panic

My approach as weird as it might be is... just dont make technical debt.

Why would business care about giving you paid work on something they cannot see and which might not be necessary in the long run (at least in their eyes)? They at most wont understand why do you want this.

Or worse, they will see you as trying to make free work for yourself. Its just easier not to mention fixing technical debt and just not to make it at all.

Need a to fix something quickly and it will bite you in the long run? Don't fix it quickly, just say that it needs a lot of time and fix it properly and poof, no more technical debt.

Don't ask to refactor later, refactor now and make it proper. We would never allow people who make houses skip few steps since we need it now, so why is it something allowed for us to do?

Business expects you to do your job professionally so they must also acknowledge that development takes time and that there cannot be skipped steps.

Collapse
rfornal profile image
bob.js

If you have a relationship with the business where this works, that's amazing and go for it ... I spent five years in a Junior position where I was pushed into a "got to get it done now" mentality. There was no time for tests, no time for refactoring.

Later in my career, as a Senior developer, I was at another company with a completely different culture where I was able to propose things like major refactoring (3+ months, including heavy test coverage) and was able to "(not) make technical debt."

Your premise could work in some cases, but not many within the companies I've worked with over the years.

A company can be moved toward the mentality you are presenting, but most are not there and that's where the approaches Matt and I are proposing in our articles are so important.

Collapse
integerman profile image
Matt Eland Author

The other factor to remember from technical debt is that it's not necessarily developer mistakes or cutting corners. Sometimes it's pursuing a business strategy that changes, or using version 4.2 of a library but version 5.5 was just release which patches security vulnerabilities in your version. Additionally, almost nobody starts with a blank slate. No matter how good you are, you're eventually going to inherit other people's code so it's important to have communication, detection, and mitigation strategies once technical debt is present in a system.

Thread Thread
rfornal profile image
bob.js

My co-workers just pointed that out as well ...

Collapse
sebbdk profile image
Sebastian Vargr

Quite a long article, did not have to read in depth atm.
But i find the subject interesting, so will come back. :)

My learnings have been that when i started translating technical debts to business goals impedance and money, then' my managers started listening more.

Collapse
integerman profile image
Matt Eland Author

Yeah, maybe I should have chopped this one in half, but there wasn't as clean of a break in this one's contents. It's easier to break out data presentation with management (a future article) and strategies for paying down technical debt (a near future article), but this one defied splitting and I felt particularly passionate about it so... yep, holy word count, Batman.

Collapse
geomc profile image
Sascha

A very good article on the subject! On point.

Collapse
integerman profile image
Matt Eland Author

Thank you! I'm giving my first conference talk in January and will be talking on the subject, so it's a bit of a rehearsal on content for the presentation as I start prepping my slides and outline.

Collapse
steelwolf180 profile image
Max Ong Zong Bao

This article is really awesome I like the part of the analogy of farming to allow the business stakeholders to understand what does it mean for software development.

Collapse
integerman profile image
Matt Eland Author

Thank you. That means a lot.