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.
Remember to 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
Have you done an exercise like this with your team or company? How did it go? Did it help? What more would you add here?