Good engineers tend to fix things right away when they notice something wrong in the code.
Imagine you have such an engineer on your team (hopefully, you have many!). When they find technical debt in pre-existing code, they rewrite everything they see and leave it in significantly better condition.
We should be able to stop there and call this a great thing. We should, but we can’t because, sometimes, this kind of initiative is a trap.
In this case, the engineer had something else they should have been doing – finishing a feature. But because they spent time fixing the tech debt, they delivered the feature weeks late.
On the one hand, coming down on this too strongly seems silly since the engineer was still productive and added value to your process.
On the other hand, they prioritized the wrong task at the wrong time. As a result, they might’ve solved one problem, but they ultimately created another with the late feature (and not just for themselves, either!).
What if the engineer logged the technical debt instead? Instead of thinking they need to care for every issue they see, with a system, they can record them with the confidence they’ll be addressed later.
As the engineering manager (EM), it’s your responsibility to create and maintain this system. But you also need to make the changes in your team’s culture that’ll make such a system possible.
Build a culture of Boy Scouts
You’re a lucky EM if you have the problem mentioned above. Some have the opposite one: engineers who ignore mistakes in other people’s code.
You’ve likely heard of the “Boy Scout’s rule.” But if not, know that when you see a piece of code, following the rule means leaving it in better shape than you found it. This could be as small as correcting misspelled text or fixing a style issue.
Some engineers, like I’ve said, can take this too far. Still, technical debt will never get logged or addressed if no one gives it even a little bit of attention.
So, your first step in building a system to track and log technical debt is encouraging your engineers to:
- Keep their eyes open for issues in the code
- Fix issues that don’t take too long (for example, less than an hour)
- And log the problems that are too big to address now
The main point is that your engineers feel responsible for the code they see. As a result, the technical debt gets tracked, and your team is alerted that something’s wrong – nothing gets lost in the chaos.
But don’t just tell your team to do this – show them the value. Show them how it keeps the ship moving and maintained while helping them balance their responsibilities in a productive way.
You won’t convince everyone, but with enough time and effort, you’ll convince most. And when successful, you’ll notice logging technical debt becoming second nature to your team.
Establish what exactly counts as technical debt
Let’s say you’ve built a culture of logging technical debt, and your team does so regularly.
Now, you have another problem. As soon as you open the log, you’re flooded with hundreds of entries from the past week alone. It turns out your engineers are perfectionists (as many of us in this industry are) and label every shortcoming as technical debt.
There’s no possible way your team will have enough time to go through it all. To address this, you have to be clear with your engineers about what actually is technical debt.
The major question they need to ask themselves is whether the issue:
- Affects the feature or product in a way that impacts the user experience or business
- Or whether it’s something that will make the code “cleaner” but will otherwise not have a noticeable effect
Your engineers may question why they should care about the business side of what they do. This is only natural – you likely did the same when you were one. But you also now know you need that buy-in from the people in your company responsible for the business end.
This isn’t arbitrary – a company needs these different sides and perspectives to function, grow, and thrive. Help your engineers to see these other sides and perspectives and truly understand them just the same as you do for the business end and engineering.
Tag everything
Unfortunately, as you may well know, logging technical debt is only half the battle. The other half is making sure it's logged correctly. Otherwise, the log turns into an incomprehensible mess.
If you’ve never managed this before, here’s what to do.
First, store the log in an accessible location and ensure it’s easy to update. The system or platform doesn’t matter as long as it achieves those two things (and allows you to have a system in the first place). You can use GitHub or Notion, for example.
Next, determine how you’re going to tag each piece of technical debt. You can do so according to a wide range of categories, such as:
- Date introduced
- Severity (e.g., low, medium, high, critical)
- Services/components affected
- Impact on team productivity
- Impact on user experience
- Impact on business revenue
- Impact on code quality
- Estimated time to resolve the issue
- Estimated cost if the issue is not resolved
- Root cause
- Risk of further issues due to this problem
- Visibility
- Existing workarounds
- And so on
The most important of these is severity, as this will define much of your prioritization. Mark something as critical if it needs to be addressed right away. Also, note if the issue needs to be addressed 4-6 months from now or can be handled a year or two down the road.
Do not let anyone slip on this. Show them examples of what you’re looking for and consistently hold them to what the system needs.
Anything else leads you right back to chaos.
Make changes as necessary
Systems rarely remain relevant without change. It would be nice if your engineers could affect the needed updates, but they don’t have the same bird’s-eye view you do. And in order to continue benefiting from tracking and logging technical debt, you will have to make these changes.
For example, if you know you’re not going to have a major deadline in the coming month, consider allowing your engineers to log more things as technical debt than usual. Adjusting your policy on the go like this can increase the amount of tech debt your team can process, but this demands regular attention on your part.
You may also get feedback from your team members indicating something’s not optimal about the system. Maybe the amount of tags people add makes the log hard to read. If so, consider simplifying your tags or moving to a platform that’s easier on the eyes.
Some changes might also be on a larger scale, such as when you know resources for technical debt are going to be reduced, and the team should only log the most important debt for a while. Another example is when long-term priorities shift, meaning you need to address certain forms of technical debt faster.
While tweaking your protocol can make for a highly adaptive team, just make sure you don’t confuse your colleagues by making too many changes too quickly.
Build and earn trust
Remember the engineer in the opening example? If they truly are a perfectionist, they may want to do everything themselves immediately because they’re concerned that, if they don’t, no one will.
Logging debt builds that trust. You’re effectively replacing a “no” with a “yes.” You’re:
- Telling them not to take care of the issue themselves
- Giving them an alternative
- And telling them someone will care for it at some point
This, of course, requires regularity and following through on your word. Engineers like them will feel less like lone rangers and more like you have their backs.
But you’re also building trust with the business side by:
- Keeping costs within acceptable limits
- Delivering work on time
- And ensuring your engineers aren’t going rogue
Doing so exponentially increases your chances of getting the help and leeway you need when addressing tech debt and other issues.
But none of this works unless you’re earning this trust over and over. This is your priority, ensuring what you say will happen happens.
The short version: log that debt
Logging and tagging technical debt sounds like a simple task, but when done wrong, it creates delays and other problems.
As the EM, you can build a system that prevents these issues:
- Build a culture of Boy Scouts: train engineers to keep their eyes open for code issues, fix issues that don’t take too long, and log problems too big to address within that timeframe
- Establish what is and isn’t technical debt: you can’t log everything, so make sure your team knows what counts
- Make a clear system for logging technical debt: especially important is how you tag your entries
- Adapt: make changes to your system as needed
- Sustain your system over time: discouraging engineers from immediately addressing technical debt requires trust in the system – so build and earn that trust
EMs see the big picture. As one, it’s your job to set up systems that work and that people find easy to use.
You will spend some time first not only on designing your system but also helping your engineers use it until it becomes second nature. Once that happens, you’ll find you’ve planted roots for a culture of attention, trust, and responsibility for technical debt.
Coming up
Join me on Friday (March 7th), when I’ll share some tips on how to master one-on-ones as an introverted engineering manager. Subscribe below so you don’t miss out!
See you then!
Want more tips on leading effective software engineering teams?
Join my newsletter if you’ve found this content useful
Originally published on Medium.com
Content in this blog post by Alex Ponomarev is licensed under CC BY 4.0.