Visualizing Technical Debt

Ward Cunningham, inventor of the wiki and one of the creators of eXtreme Programming, first described technical debt in 1992 this way:

Shipping first time code is like going into debt. A little debt speeds development so long as it is paid back promptly with a rewrite… The danger occurs when the debt is not repaid. Every minute spent on not-quite-right code counts as interest on that debt. Entire engineering organizations can be brought to a stand-still under the debt load of an unconsolidated implementation.

Many teams we encounter are laboring under a mountain of technical debt. It got that way for a variety of reasons, often outside the team’s control or before the current leaders started. So, while it’s useful to consider how to avoid adding more technical debt to a system, the pressing challenge for our clients is often, how do I start getting out from under all this technical debt?

Make it Visible

As we always say, “If you can’t just fix it, make it more visible.” And that’s the right first move here. Make your technical debt more visible and concrete. This allows product and technical people to reason about it together in order to incrementally resolve it. Here’s how…

Find or create an architecture diagram for your system as a black and white line drawing. Gather the team around it. For each item on the diagram, ask, “How safe does it feel to make changes in or around this part of the system?” Have a conversation about it. If a particular part of the system feels scary to touch, there’s a high level of technical debt there. Color that part of the diagram red. If a part of the system isn’t exactly scary but it feels high-friction, like it requires extra care, color that part of the diagram yellow. If a part of the diagram feels safe and easy to work with, leave it white.

Have a bias towards marking things red or yellow. If even a few people on the team find an area of the app sketchy to work with, that’s friction to highlight. There’s often one senior member of the team who’s the only one who feels comfortable in certain old and rusty parts of your code. That person may insist, “it’s fine,” but it’s not. We’re visualizing the team’s collective ability to move fast in our system.

You’ll probably have to make distinctions within items on the diagram. For example, someone might say, “The part of this billing service that deals with discounts is pretty scary, but the rest of the billing service is fine to work with.” Ok, add a box within the billing service labeled “Discounts,” and color it red. Go as granular as you need to in order to distinguish where your technical debt lives.

Tech Debt Heat Map

Once you’ve talked about each part of the diagram, you’ll end up with a heat map for the technical debt in your system. Notice this didn’t require any fancy new tools or quantitative measures. You’re just visualizing where developers’ intuition tells them “here be dragons.” This works because systems low in technical debt, systems with good design, are easy and safe to modify and extend.

Now that you have it, how do you use this technical debt heat map to start reducing your technical debt? Bring it to your backlog refinement, planning, and review meetings. When you encounter a feature that cuts through an area of the app with high technical debt, discuss how you can incrementally reduce the debt while you’re in there adding value. In reviews, see if you can update your heat map to account for increases and decreases in technical debt.

When you find a part of the system that you can’t seem to fix incrementally but that is affecting your customer-facing work—by slowing you down or by causing you to avoid working on certain features—model that technical debt fix as a backlog item and work out its cost of delay so it can be prioritized against customer-facing features.

By visualizing your technical debt and then including fixing it in your team’s regular work, you’ll slowly resolve the most painful parts of it and be on your way to building a system that’s easy and safe to modify and extend.

Don’t just mindlessly set aside a small percentage of time for undirected technical debt reduction. Mindfully and transparently address the most important technical debt as part of your team’s regular work.

Learn More

Interested in more valuable content for teams? Find out how you can learn more with us!

Last updated