This repo demonstrates how one or more technical teams can capture and track Tech Debt over time, using the Tech Debt Triage framework, created by Oliver Tomlinson in 2019.
The Framework exists entirely in the Read Me (below), and examples can be found in the Issues section of the repo.
- Sustainable software - Implement a lightweight evidence-based process that provides software owners with a mandate to pay-back technical debt.
- Free of blame - A cathartic exercise that encourages developers to vindicate themselves when making decisions that they believe may not be the best choice long-term.
- Feeding the maintenance stream - Maintain a register of concerns that can be used to regularly feed into the maintenance stream.
Raise an issue when a decision has been made which sacrifices one or more of the below characteristics in favour of delivery speed.
Raise an issue when a scenario has been discovered which is impacting (or is likely to impact) one or more of the below characteristics.
- Architecture
- Availability
- CI/CD
- Code Quality
- Cost
- Data integrity (durability, redundancy etc)
- Observability
- Process (inefficient/ineffective)
- Scalability
- Security
- Testability
- Throughput
Each technical debt item is logged as a GitHub Issue.
On initial creation of the issue, it should provide a lightweight explanation of the technical debt, just enough to prompt the discussion in the next triage session.
The New label is applied so it can be easily identified in the next triage sesison.
The team as as whole will come together on a regular candance. Monthly works well, but change as neccessary. This coming together of the team is called the triage session. It can be done remotely or in person, or a mix.
During each triage session, new and existing issues that are not yet fully refined will be explored, assessed, and further refined to produce the following outcomes
- Domains affected
- Impacts (Characteristics) have been identified
- Trigger points have been predicted
- Why does this debt exist?
It is expected that some issues may take many rounds of triage before the technical debt is understood well enough to be accepted. If the item is not fully refined, apply the needs refinement label, and work on it during the next triage session or offline.
Once the refinement is complete, the issue is given the label of accepted.
Without being clear about what is affected it is impossible to assess the severity of the technical debt.
Labels are applied to the GitHub issue to easly identify which business domains or product domains are affected by the technical debt.
It's entirely possible that one item of technical debt will have many unsavory characteristics, so underestanding the breadth of the debt will help us define suitable trigger points.
Labels are applied to the GitHub issue to easily identifiy common themes.
The trigger point defines a condition that when met will give software owners a mandate to pay back the debt.
Trigger points will need to be reviewed over the life-span of the software for correctness as new information comes to light and must be factored in.
Making trade-offs and accruing technical debt is absolutely neccessary in order to perform effective agile software delivery. If trade-offs were never made in favour of meeting a gold standard, we would loose the ability to release value often to customers and the agile process would break down.
We make technical debt decisions every day and keeping track of them in our mind will only scale so far. As we build and own more software domains our ability to retain the technical debt in our mind will diminish, and it is highly likely that we will overlook or forget important things. The log will help us to realise and visualise how many technical trade-offs we make in persuit of delivery.
Sometimes technical debt is never paid back and for seemingly good reasons. By taking an evidence-based approach it will enable us to identify when debt should be paid back with a clear mandate to do so.
Tracking the debt will hopefully tackle this common expectation/reality problem that has been whitnessed in other long-living software domains.
Expectation
We won't do X now because Y is happening in the future, which negates or surplants the effort of doing X.
Reality
Y never happened. The impact of not doing X is felt for longer. Problems caused by not doing X are compounded. Doing X becomes harder over time as the problems manifest deeper.
This reality is particularly dangerous for software domains that are expected to have a long lifecycle.
Owners of said software domains will organically change over time and knowledge loss will always occur to some degree. Putting in place a technical debt log will also help mitigate this knowledge loss scenario and help us to build healthier long-term software domains.
Just because you don't like it is not a sufficient reason to raise it as technical debt. At this point, not liking something is just your opinion.
However you can transform your opinion into a technical debt issue by asking yourself the question, "Why don't I like this?" and answering it honestly.
It is quite possible that your underlying motivations for not liking something may actually be rooted in sensible reasons that relate to the chracteristics. If your reasoning doesn't map to a characteristic it is unlikely to be accepted as technical debt.
This Repo is not for tracking bugs or product/platform behavior issues.