Today I want to talk about tech debt and having a plan as a team to fix it.

Most software companies that have been around for a number of years have a codebase that roughly reflects the company’s journey to date. There are hacks, shortcuts, patches, rush jobs and decisions that in hindsight were poor. Generally, we call this “tech debt”.

From Wikipedia: Technical debt (also known as design debt or code debt) is a concept in software development that reflects the implied cost of additional rework caused by choosing an easy (limited) solution now instead of using a better approach that would take longer.

Tech debt isn’t necessarily a bad thing, just like monetary debt isn’t necessarily a bad thing. However, it’s bad when you don’t have a plan to pay it off or you’re getting into more debt recklessly. The pragmatism of taking on debt is something you hone over your career and coding wisdom is basically this.

So let’s talk about that plan. By this point in your company's life, you might have some new engineers, you might have some longer-serving ones. You might have more junior developers and you might have more seniors. They’ll all have their own idea of how the system works and what it would look like if it were “perfect”.

Target State Architecture (TSA) is that “perfect” case. However, the problem for most companies is that it lives in the back of the mind of the most senior or long-serving engineers. Maybe the CTO knows, but not many others would. Some engineers might know bits of the future and most likely only know bits of the present.

What my advice is for all teams is take time to have a workshop to get your team to discuss, debate and agree on a TSA. The “team” here can have varied definitions. It might literally involve everyone in your org, but obviously, with a large team, these become impractical. So you might instead opt for seniors or a mix of all. I think a representational subset is best (but remember all is a subset of all… maths!).

During this workshop, you should do a couple of things.

TSA Workshop Part One: Agree on the Current State

The first thing is to have everyone draw on some paper their current understanding of the architecture. (Now, this is where I recommend breaking your architecture down based on team size. If you’re 10 devs in a garage, you can have the whole architecture drawn, if you’re in a FANG like company, maybe go into product teams). By drawing the architecture, this simple exercise will highlight developers knowledge gaps of the system. Maybe they haven’t interacted with that part yet or they simply don’t know where some data goes or comes from. That’s fine, but we hope to address it over the course of the workshop. It is crucial that every developer understand all moving parts, at at least a high level, for a team to succeed. I’ve seen a large project struggle along because this wasn’t the case.

Once everyone has their diagram, you can start drawing up, perhaps on a whiteboard, the current diagram. You might have to pull together multiple diagrams to get the full picture. Each system might come with a short (30-60 seconds) explainer on what that component does.

TSA Workshop Part Two: Agree on the Issues

So you’ve got your present architecture. Maybe it looks like a monolith with a few services around it, maybe it looks like a full-blown microservice architecture, maybe it’s just a frontend codebase but its a mix of frameworks held together by hope and webpack.  (I’ve done these exercises with mobile app codebases and backend systems, it’ll work, just choose a level of detail suitable to the people in the room and the codebase at hand). Now it’s time to talk about the problems with it. What’s working well? What’s working poorly? Is something hard to add to? Hard to change? Risky to change? Does something feel like its done its dash? Talk about all these things and it’ll put you in the mindset for the next step.

TSA Workshop Part Three: Agree on the Future

The next step is to go back to individual diagramming - this time drawing the perfect architecture for your system.  You’ve just learned what you’ve got, what is working and what isn’t, now draw a system to address all those. Let your imagination run wild. The idea is to draw the perfect system, not a practical system, not even a system that’s achievable in the next year, but something you’d like to get to one day.

Once you all have finished your diagram, it's time for another discussion. Work out what might make the most sense for your TSA. If you feel yourself or see team members disagreeing hard, the trick is to make sure everyone has the same information. People with the same information generally come to the same conclusion - we just suck at doing this as humans.  After you’ve agreed on your architecture, it’s worth drawing it up on the whiteboard again.

How to Make the Most of your TSA

The team should now be in agreement about the TSA. Following the meeting, a team member should create a digital version of the current architecture and TSA diagrams and print them large, like A3,  and paste it to the wall. These two diagrams will come in very handy for task planning, discussions, debates, sprint planning and many more times. Not many companies do this, but it’s a great productivity win to be able to just point at the diagram rather than drawing a new (potentially incorrect) diagram every time you want to reason about the system.

Another big important win of having both a TSA and agreement as a team to work towards it is that arguments simply finish faster. Most subsequent code changes can be categorised as towards or away from TSA. If you see something away from the TSA, it could be a good time to catch that, call it out and maybe approach the problem in a different way.

When a new hire starts, you should walk them through these diagrams, and your plans. This will be a very efficient way to groud their thinking and start making choices that are pragmatic and effective. It’s also a good thing to talk about in a late-stage hiring interview too, giving a candidate the positive impression that you are aware of and have a plan for your technical debt.

Finally, keep these diagrams and TSA up to date. The current state diagram will change pretty quickly maybe monthly it might need a refresh, and the TSA one might change less frequently, perhaps every six months. Like most tools, they’re only as good as you make them. Taking the time to maintain them will ensure you continue to save time as you build your system and fix your tech debt.

Finally, having a TSA is not a silver bullet. It doesn’t mean you’ll get there and be tech debt-free. Really, no company is free of tech debt. But it does mean you’ve put in a system in place where the team has felt empowered to realise what they’ve got, how well it works and where they want to get to, and that is super powerful.

Best of luck!

Sam