Technical debt is the future cost of maintaining or updating code written quickly or without enough attention to quality. Like a loan, a shortcut can help a team deliver sooner, but the interest may appear as added complexity, higher maintenance costs, and longer development cycles. Taking on debt is not always a mistake; leaving it untracked can make it a burden. section 5.1.2
A lead developer helps keep technical debt manageable while the team meets its delivery goals. That means working with the project manager and developers to organize debt alongside features and bugs, using team feedback to estimate the work and weigh priorities. section 1.1.3 section 1.2.2
Use both prevention and planned repayment:
- Prevent avoidable debt by considering scalability and maintainability when designing a solution. Code reviews, clear documentation, linters, and automated tests can help catch problems early. section 6.3.3
- Document coding standards, deployment steps, and the reasons behind technical decisions. This gives future maintainers a record of what was done and why. section 5.1.2
- Surface pain points through retrospectives or other team discussions. Keep a prioritized list of mitigation tasks, estimate their effort, and bring small chunks into sprints when capacity allows. section 6.5.2
- Explain the effect of debt to the product team. For substantial work, identify what needs changing and plan the effort rather than treating it as an invisible development task. section 6.5.2
Prevention and reaction serve different needs. A reactionary approach fixes problems as they arise, including bugs and security vulnerabilities, but repeated patches can leave code harder to maintain. A preventative approach spends time earlier to reduce that risk. Neither removes the need to notice and address debt already in the codebase. section 6.3.3
When debt slows feature work
A homegrown client-side data-management component made development at least twice as slow and more complex. The proposed remedy was to replace it with an open-source implementation. The practical first steps were to explain the impact to the product team, list the needed changes, prioritize them, and estimate the work. section 6.5.2
Table 5.1 Effects of proper technical documentation on the development workflow (view table figure)
| With proper technical documentation |
Without proper technical documentation |
|---|---|
| Developers clearly understand how the code works and how to use it. |
Developers are left to figure things out independently, which can lead to confusion and mistakes. |
| Developers can easily find the information they need to complete their tasks. |
Developers may need to spend a lot of time searching for information and experimenting to understand how things work. |
| Developers can quickly identify/fix bugs and make changes to the code. |
Developers may have a harder time identifying/fixing bugs and making changes to the code. |
| Developers can easily collaborate with other team members. |
Developers may have difficulty working with other team members because they aren’t on the same page. |
| Developers can easily onboard new team members. |
Developers may have difficulty onboarding new team members because they lack the information they need to get started. |
Compare how documentation, or its absence, affects finding information, fixing bugs, making changes, collaboration, and onboarding. section 5.1
Treat technical debt as work that needs visibility, not as a vague complaint. Record the decisions that created it, make its costs understandable, and reserve time to reduce the most consequential items. section 5.1.2 section 6.5.2
