Before you can log technical debt, of course, you should know what it is and why anyone should care about it. The Wikipedia article on technical debt sums everything up nicely. For more, in-depth, information I strongly recommend going through these articles written by Martin Fowler on the matter.

Why and Who Should Log Technical Debt

Why should anyone log technical debt? Why not just tackle technical debt as we see it and leave the code clean as a whistle? Technical debt can indeed be inadvertent and you can simply stumble upon it like that (see the Technical Debt Quadrant). If it does not affect the estimate for your current task, it is your duty as a professional developer to fix it without fussing. But more often than not, it’s not the case of small inadvertent mistakes, but huge design flaws or deliberate shortcuts to meet development costs and deadlines. Maybe the team has been cutting corners for weeks, months or years to save up on costs and never intended to repay the debt. Maybe their intentions were good, but didn’t log anything and then forgot.
I got a bit side-tracked with stories there, but let’s get back to “why log technical debt?”:

• The team will forget it and get hit by the interest rate when they least expect it. The estimation accuracy will go south from that point on.
• When estimating, the team should know how the sprint backlog is affected by the technical debt backlog. It’s easier to keep score if you have a technical debt backlog available.
• As any other task, refactoring should be planned by the person (or people) in charge of planning (PO, project manager, the Agile team, etc.). Planning also has to take into consideration the life-cycle and the expected life span of the project. No one cares about technical debt on a project that has reached the end of life. But a project that is expected to work for the next 20 years, is highly sensitive to accruing technical debt. Similarly, a start-up that is not sure will make the next funding round is more sensitive to time and resources than technical debt, but must have a debt backlog to tackle after funding.
• Engineers tend to be religious about technical debt (especially what they perceive it as introduced by someone else), while business people and project managers tent do ignore this issue altogether. Paying the debt may result in short-term revenue decrease or pushing back committed deadlines. It’s only further down the line when engineers get to say “I told you so”. The development grinds to a halt, people start abandoning ship and 90% of the time is spent debugging old code. So, to have some common grounds on this issue, the technical debt must be properly logged. Engineers should understand that not all debt must be repaid and all stake holders must understand that some of it has to be paid in order to keep the project afloat.

Who should be logging it? The development team, of course! They are the ones whose work is impacted daily and they are the ones who best understand it.

Managers, Clients and I… We Don’t Speak the Same Language

Technical people log the issues, but that doesn’t mean no-one reads what they’ve logged. Management and clients should evaluate the short-term and long-term risks of what was logged and plan the repayment of the debt in accordance with their business plan. But wait… they will not understand a thing from reading “Multiple occurrences of runtime exceptions being caught and swallowed, must investigate the impact on reliability”. Those words will mean nothing to a non-technical person. Maybe even a technical person who hasn’t worked in a programming language that supports exception handling will find himself lost.

Sell your technical debt backlog like you would sell your car! Would you write an ad that says “Nice car for sale, has 6 cylinders, runs on gas that is injected via injectors under high pressure into the combustion chamber, does not have the carburetor fuel system which is kinda old for 2015. Surely you want the injected one…Call me!”?  I guess most buyers won’t know what you’ve just said and it doesn’t really matter because they are interested in what business value they can get out of it. Like can they fit their moonshine in the trunk or do all the kids have seats? Those details are for mechanics (or in our case, software engineers). So, when logging technical debt issues, make sure to write what feature is impacted; How much time the team will waste in future development and/or debugging; How often this issue needs patching and worked-around, and most importantly, paint a pretty picture of the team and the stake holders being thankful after the issue is solved! Note that technical details should still be present in the log. The engineers tackling the issue will need to know what the issue is. Adding extra information for other stake holders is just the developers’ gift to them… and themselves actually, because now the issue has a fighting chance to make it into the sprint.

Example of a Properly Written Technical Debt Ticket

Let’s get back to our previous example of. “Multiple occurrences of runtime exceptions being caught and swallowed must investigate the impact on reliability”. Reading this, I can’t even begin to imagine what that means for our beloved project. It compiles, it runs, smoke tests pass, integration tests pass… why change exception handling if it works? So let’s see how we can sell this story better:

First off, the title (or summary in some issue trackers), should not be a technical description. Remember that this field is what the stakeholders will see in the backlog, so it’s important to summarize the impact, not the technical issue itself.

Secondly, you might want to sync with the team on what minor, major, critical and blocker mean for your technical backlog. Do not oversell the issue priority because this will soon be picked up by the decision makers and they will make it harder for you to pass technical tasks in the sprint backlog!

The affected versions field is also important as the master branch and the latest GA will likely be more sensitive to debt than older branches.

If you usually track components in your issue tracker, then pick the likely affected modules from your project. If not, just make sure to log the affected functionality in the full description (i.e. Billing, Admin GUI, Logout, etc.). However, I strongly recommend you do track components/modules on issues because it will make it easier for you to locate technical debt stories when planning work on specific components.

You will need a way to tag your technical debt stories. Either create a separate backlog just for that or create a tag for the technical debt if the ticketing tool supports that. It doesn’t really matter as long as you and your team can locate and track the issues’ statuses.

Bare in mind that you should visually isolate the technical description from the “marketing” description. “Fixing these issue will help the team maintain higher code quality and prevent critical issues from going unnoticed when deploying. It may also solve a randomly occurring bug in production“, this is the pretty picture I was referring to earlier. The non-technical decision makers should be able to quickly locate this in the description body as well as the per-feature description of the impact. It’s this section that will influence the decision to tackle the issue, postpone it or drop it.

It’s always a good idea to include some estimated costs for work done so far, for interest rate per sprint and cost to fix. In this case, I’ve added an extra estimation for an intermediary resolution. Sometimes an approximate solution or a temporary fix will keep everybody happy if it’s cheaper. In this case if the stake holders think that 4 man-days is not a sensible estimation, they might settle for better logging that will provide better visibility into the problem at a fraction of the cost. For the sake of the example I’ve used man-days on estimates but obviously you should use whatever unit your team uses for estimating stories.

Last but not least, as the person logging an issue, never assume that you will be the one solving it. Also, never assume the one solving it, knows enough about the matter to tackle it in a professional way. For those reasons, always provide some references on the subject and maybe some explained best practices. Besides guiding the team, references also have the added bonus of making your issue more credible in the eyes of the decision makers.