What are the crucial key items in recording technical debt?

Question

I'm setting up a technical debt register at The Office and want to make it a fairly comprehensive tool.

What are the key pieces of information that we should be recording?

Giraldo

Gosh, we just use our normal issue tracking system and mark the issues with speicific tag/category. – Bick

Love the question and am looking forward to the answers. Perhaps you should specify one issue per answer so we can use voting to see which issues are more important then others? – Beechnut

Answer 1

First of all - you want to keep your register very simple, otherwise the overhead of maintaining the register will stop people from using it and waste more time than actually fixing the technical debt it was meant to solve.....

If you still decide to go ahead, I'd suggest keeping a simple register which is a flat file / simple database / Google spreadsheet with the following fields:

• Module/component name
• Description of what needs to be fixed (you might have a list of categories but I think this also need a text one-liner)
• Estimated fix time in days (I'd be inclined to insist on whole numbers of days, otherwise people will have a tendency to start logging trivially small things)
• Which developer incurred the debt (and provided the fix time estimate)
• Which project the debt was incurred on (any by implication, which project manager is accountable)

Rules are as follows:

• Developers are expected to be transparent about technical debt. If a developer needs to incur technical debt due to project pressures, the developer should add this to the log with their estimated fix time.
• Project managers are accountable for technical debt that they run up (i.e. did they pressure developers to take shortcuts?). They should be able to justify a solid business justification for the total debt run up, and propose what should be done to fix it.
• If no technical debt is noted, then the code is expected to be of top quality and pass any relevant code reviews. If technical debt is noted, then the developer gets a "pass" for whatever is noted (the review might instead helpfully consider the accuracy of the debt logging and ideas on what should be done to fix).
• Developers are expected to give fair estimates for the fix time. If they say it will take two days to refactor the architecture, then they shouldn't be surprised if they are given two days to fix it at some later time....

I think this approach will create a good dynamic overall - developers have a responsibility to be transparent and think about how to solve technical debt, project managers / business leads have to make the trade-offs but it is clear that the costs of debt are their responsibility, the best developers and architects will get kudos for completing the tough projects while also keeping technical debt under control.

Gemagemara

one of the proposal on the structure of debt register is in this article - dl.acm.org/citation.cfm?id=2119668, authors call it "Technical debt template" – Stonework