The Wall of Technical Debt

“Technical debt” is a metaphor for all software design choices that turn out to be suboptimal, no longer valid, or just plain wrong. These choices incur a cost on future development, and the shortcuts taken today will later slow you down until you “pay back” the debt by fixing the problems. And it’s not only code: Artifacts like architecture, documentation, tests, and domain models can all suffer from technical debt.

Technical debt can severely drag down development. And paying back all debt by replacing all software isn’t usually very feasible either. But, like financial debt, technical debt is not always a bad thing. Debt allows you to invest in something before it makes money. Taking shortcuts when bringing a product to market allows you to test a business model cheaply, and it makes it easier to throw away the code if it turns out to be a bad idea. And often, the debt exists because the business has grown and evolved, and the design choices that were valid early on no longer are.

All this to say that the problem isn’t technical debt; it’s unmanaged technical debt. In any company, the CFO knows exactly how much financial debt there is. There are spreadsheets, quarterly reports, payment plans, and options to refinance or sell debt. But ask your CTO how much technical debt your organization has, and you’ll get an awkward “uh… a lot?” as an answer.

So how do you manage debt in a fast-moving agile project?

The Wall of Technical Debt is a surface in your office where you visualize issues on sticky notes. It’s easy to start and maintain, and yet it has a profound impact on how you choose to add, reduce, pay back, or ignore debt. It’s by no means intended as a complete solution to scale the management of debt, but it works precisely because it requires no buy-in.

Creating Your Own Wall

Creating your own Wall of Technical Debt is simple: Make the debt visible, build a habit, negotiate regularly, and give away control.

Example of a Wall of Technical Debt, from @Pelshoff

Image by Pim Elshoff. Licensed under a Creative Commons Attribution 4.0 International License.

Make It Visible

Pick a wall in the space where your team works. Make sure it’s publicly visible. Label it the “Wall of Technical Debt.” Draw a nice dramatic logo. Make sure there are sticky notes and markers around so people can easily add to it.

Build a Habit

Whenever you work on code and encounter technical debt:

Ask yourself: What made you slow? What made the code difficult to understand? What caused a specific bug to be hard to track down? What should have been better documented or tested? Write down any technical debt you encountered on a sticky note. Keep it short, but make sure you’ll be able to understand it later.
Estimate the opportunity cost, i.e. the time you would have spent on something else if the issue at hand didn’t exist. Write it on the sticky note. Agree on a notation for time, such as tally marks or dots per half day. Being visual is more important than being precise.
Estimate how long it would take to fix it, and write that down as well.
Optionally, write down how to fix the technical debt. You’ll probably want to do this part in an issue tracker, so if you do, write the issue ID on the sticky note.
Put the sticky note on the Wall of Technical Debt.
Whenever someone runs into the same issue, add more marks to represent the time they lost.
Over time, you’ll want to add some categorisation and structure. Let these emerge, resist organising it prematurely.

Don’t forget to also add sticky notes whenever you introduce new technical debt yourself. And be honest. There’s no shame in this, because you are not your code. Remember technical debt is an investment, not a crime — unless you’re hiding debt, in which case you’re cooking the books!

When this becomes a habit, the wall becomes an information radar of the state of your system.

Negotiate Regularly

As the Wall of Technical Debt grows, people in your organization might get a little nervous. That’s OK! The debt was always there; you only made it visible. Hopefully some of the habits start changing.

Whenever someone gets up to add another dot to an existing sticky note, discuss it with the team. Compare the cost of the measured wasted time to the estimated time to fix the debt. Sure, it might take a day to fix the code, but if you keep losing two hours over it every week, the time spent fixing it will pay for itself soon enough.

Or, perhaps fixing it isn’t worth it. That’s no longer a matter of aesthetics or opinion. Rather, it’s a matter of empirically collected metrics. Congratulations, you’re negotiating tradeoffs as a team.

Meanwhile, when someone adds a sticky for newly discovered existing debt, consider if it’s something the team could fix right away. Of course, it’s perfectly fine to put it on the wall; that’s what it’s there for. However, when you’re introducing new debt, it’s different. Consider if the team could choose not to take the shortcut and instead fix the code while it’s still cheap. The question shouldn’t be “Do we have time now?” It should be “Is it worth paying interest on this later? How much?” The answer could range anywhere from “It doesn’t matter, just commit it,” to “Lots of things will depend on this, so let’s get it right before moving on.”

The point is not to fix all technical debt. The point is to learn to negotiate when to add it, when to fix it, and when to avoid it. Before, this happened mostly invisibly: Individual team members added or fixed debt without knowing all the facts. Now, the collective brain power of the team can be applied, using real data.

Give Away Control

Now we get to the real magic. Because the Wall of Technical Debt is so visible, managers should start to take notice. (If they still don’t, use a fat red marker to add some € or $ signs to the Wall. Money is the universal language, and lost money stings twice as hard.)

Normally, when a team asks for time to spend on technical debt, there’s no direct tangible benefit to the users or the business. A manager can’t decide whether those fixes are of critical importance, an attempt to play with shiny new tech, or a desire to have prettier code. Even for a manager with a deep technical background, if they’re not directly involved with the code, it’s impossible for them to judge the importance of a fix.

But with the Wall of Technical Debt, it’s different. Now it’s not about opinions. It’s not about the desire to be a craftsperson who writes elegant code. It’s not about solving challenging puzzles. This time, it’s about facts, numbers, debt and interest payments, and returns on investment. You’re speaking the manager’s language. Good code as an asset, bad code as a liability. They’re trained to look at the numbers and make decisions. They’ve got the methods for it: CBA, OODA, PCDA, SWOT, …

So now, give away control. The manager knows more about the company strategy, the budgets, the risks. Let them decide, with your help, what to fix and when to plan it. The numbers enable that.

Tips and Traps

Don’t start with a complete audit of all your debt. Sure, you could spend a few days identifying all debt. But then you need to get buy-in, and set up dates, and you’re making it a big thing. “We’ll do it during Summer” or “after the big project is finished” or whatever the local euphemism for “never” is. Instead, a single sticky note on the wall today brings value today. You can always do your big audit later; just don’t make it a bottleneck.
Without tally marks or dots that represent real incurred costs, you’re back at opinion, and some of the things that bother you may not actually impact future development. This is why real-time tracking is important. By only adding problems when you run into them, your Wall of Technical Debt will represent actual time wasted and not aesthetic problems with no impact on development. This is important because you want to build a habit of negotiating debt, and not simply make a one-off effort and then go back to the old ways.
It works the other way around as well. If you encounter ugly or strange code but you didn’t lose any time over it, don’t mark it. We’re not measuring whether you like it, only whether it costs time.
Don’t skip the physical wall. Resist the urge to put everything in a digital tool such as a bug tracker. Logs and metrics only have an impact when people look at them. Digital tools make it easy to hide things, whereas the wall is visible — confrontational even.

Conclusion

I started writing and speaking about the Wall of Technical Debt in 2013, after my team and I had developed a first version. One of the first companies that adapted our approach, was a small startup I was consulting for. The little wall space they had was already used by business plans and app mockups. So the team put the sticky notes on the office’s only window. The joke became that whenever the room got too dark, they knew it was time to refactor!

More importantly, they had been stuck alternating between perfectionism and hacking things to get to market faster. The Wall of Technical Debt helped them break out of that cycle, and they launched soon after. I’ve since heard stories of teams in all sorts of companies using it successfully. Perhaps you could be next.

Credits

I wrote this article for Visual Collaboration Tools, a book that Kenny Baas-Schwegler and João Rosa are editing. It’s loosely based on “Managed Technical Debt”, Verraes 2013. Thanks to Indu Alagarsamy, Rebecca Wirfs-Brock, and Natalye Childress, for reviewing the drafts.