Reduce technical debt with diagrams

Here’s a hard truth about technical projects: non-trivial projects will accrue technical debt. It doesn’t matter how good your processes are. Over time, technical debt will grow until you are faced with the tough decision of letting the project die or actively reducing the debt.

And, as you make this decision, and diagrams will be your friend.

Justifying the reduction of technical debt

The hardest part in reducing technical debt is seldom the amount of time spent reducing tasks. It’s swaying stakeholders, convincing them that reducing technical debt is a necessity. Because reducing technical debt doesn’t add new customer features, its impact on revenue can be difficult to see.

This issue is compounded by the perceived state of the current system. If the system is performing well, why fix what isn’t broken? If the system isn’t performing well, can it be patched to work “for now”?

Of course, convincing stakeholders means meetings... which means presentations… which means diagrams. Visual representations of the current technical debt, the necessary steps to decrease the debt, and an idealized final state will go a long way in swaying stakeholders. These diagrams can (and should) also be used to correlate the effect of technical debt on long-term customer issues and satisfaction. Show how your organization will enhance the customer experience through a more stable, better performing system that you can easily add features to.

Breaking down the tasks

The constant drive for feature enhancements pushes debt further and further down the road. You can slow the growth of this debt through good processes, but you cannot stop it. Once you are finally ready to tackle your technical debt, it may be a frightening behemoth.

There’s an old saying about how to eat an elephant: you can’t do it all in one bite. You need to think of technical debt the same way. Though potentially monolithic, breaking this project down into manageable chunks makes dealing with it more palatable.

Diagrams make the process noticeably simpler. They make it easier to group the debt into logical units that can be tackled together. The process is even simpler if you have been keeping up with system and code diagrams diligently throughout your software lifecycle. Think of the components in your diagrams as building blocks. Then figure out which ones can be removed, replaced, or combined. Prioritize work based on complexity and ROI for the individual components. These steps will give you a roadmap for reducing your technical debt.

Facilitating communication

Verbal communication is a tricky thing. Words and statements are highly open to interpretation. Context, knowledge, and experience cause interpretations to vary greatly between people. While technical documentation theoretically removes ambiguity, the very nature of language prevents 100% removal.

Ambiguity is problematic when reducing technical debt. You’ll burn through time defining the current state of the system from documentation as well as reaching consensus on the endpoint simply because of differing linguistic interpretations. Time will always be at a premium when reducing technical debt as stakeholders and customers grow anxious for new features. You cannot afford to waste it.

Fortunately, good diagrams are far less ambiguous than purely written documentation. Your teams will more quickly agree on where you are and, more importantly, where you need to go.

Try this exercise: Ask a group of people to provide a universal definition of a chair. This question will result in a wide range of definitions of a chair. Now show the same group a picture of a chair. You will get the response, “Yup, that’s a chair.” There shouldn’t have been much debate in identifying the picture of the chair. Your diagrams will do the same for reducing technical debt.

Conclusion

My purpose is not to dissuade you from writing technical documentation. If your documentation is well thought out and properly maintained, it will be invaluable in any software project. It will also be an asset when the time comes to reduce technical debt. However, diagrams will provide a much-needed jumping-off point when starting the process. They will help you figure out what you need to do, reach consensus, and make your stakeholders feel confident that the decision to reduce technical debt is a necessity for long-term viability.