Technical Debt Documentation

Technical debt accumulates silently, slowing development until teams can't ignore it. Documentation makes debt visible, quantifiable, and actionable. Well-documented debt enables informed trade-offs between paying it down and shipping features.

Documentation Elements

Debt Documentation Format

Standard Template

TECHNICAL DEBT ITEM TEMPLATE
════════════════════════════

TITLE:
─────────────────────────────────────
Clear, concise name
"Legacy authentication system"
"Monolithic test suite"
"Inconsistent API responses"

DESCRIPTION:
─────────────────────────────────────
What is the debt?
Why does it exist?
When was it introduced?

Example:
"Authentication was built quickly for MVP.
Uses outdated bcrypt version, no OAuth,
session management is custom-built.
Introduced: 2021 Q2, 3 developers ago."

LOCATION:
─────────────────────────────────────
Which files/services/modules?
├── /src/auth/
├── /src/middleware/session.js
├── /src/controllers/login.js
├── Related: /tests/auth/*.test.js
└── Lines affected: ~2000

IMPACT:
─────────────────────────────────────
How does it slow us down?
├── New auth features take +2 days
├── Onboarding: 1 week to understand
├── Security reviews flag it every time
├── CI runs 15 min longer
└── Quantify where possible

COST TO FIX:
─────────────────────────────────────
What would remediation take?
├── Estimated effort: 3 sprints
├── Team members: 2 developers
├── External: Security review $5K
├── Risk during migration: Medium
└── Downtime: 2 hours planned

RISK IF IGNORED:
─────────────────────────────────────
What could go wrong?
├── Security: Vulnerability exploitation
├── Scalability: Won't handle growth
├── Team: Key developer leaves
├── Business: Customer data breach
└── Severity: High / Medium / Low

PRIORITY RECOMMENDATION:
─────────────────────────────────────
├── Urgency: Address in next 2 quarters
├── Compare to other debt items
├── Consider strategic timing
└── Next steps: Include in Q3 planning

Categorizing Debt

Debt Types

TECHNICAL DEBT CATEGORIES
═════════════════════════

CODE QUALITY:
─────────────────────────────────────
├── Duplicate code
├── Complex functions
├── Poor naming
├── Missing abstractions
├── Inconsistent patterns
└── Fix: Refactoring sprints

ARCHITECTURE:
─────────────────────────────────────
├── Monolith needing decomposition
├── Wrong technology choice
├── Missing service boundaries
├── Scaling limitations
├── Tight coupling
└── Fix: Major initiatives

TESTING:
─────────────────────────────────────
├── Missing tests
├── Slow test suite
├── Flaky tests
├── No integration tests
├── Unmaintained tests
└── Fix: Test improvement sprints

INFRASTRUCTURE:
─────────────────────────────────────
├── Outdated dependencies
├── Manual deployment
├── No monitoring
├── Scaling limitations
├── Configuration drift
└── Fix: Infrastructure initiatives

DOCUMENTATION:
─────────────────────────────────────
├── Missing docs
├── Outdated docs
├── No onboarding guides
├── Tribal knowledge
├── No architecture docs
└── Fix: Documentation sprints

TRACKING BY CATEGORY:
─────────────────────────────────────
Label debt items by category.
Enables analysis:
"60% of our debt is testing-related.
Focus test improvement."

Severity Levels

DEBT SEVERITY LEVELS
════════════════════

CRITICAL:
─────────────────────────────────────
├── Active security vulnerability
├── Regular production incidents
├── Blocking business operations
├── Must address immediately
└── Treat as production issue

HIGH:
─────────────────────────────────────
├── Significant development slowdown
├── Frequent bugs in this area
├── Customer-facing quality issues
├── Address within 1-2 quarters
└── Major backlog item

MEDIUM:
─────────────────────────────────────
├── Noticeable friction
├── Occasional issues
├── Onboarding impact
├── Address within 2-4 quarters
└── Regular backlog item

LOW:
─────────────────────────────────────
├── Minor annoyance
├── Best practice gap
├── Nice to improve
├── Address opportunistically
└── When touching that code anyway

Tracking in GitScrum

Debt Backlog

GITSCRUM DEBT TRACKING
══════════════════════

CREATE DEBT BACKLOG:
─────────────────────────────────────
Option 1: Label in main backlog
├── Label: "tech-debt"
├── Filter to view all debt
├── Competes with features
└── Single prioritization

Option 2: Separate debt board
├── Dedicated Tech Debt board
├── Own workflow
├── Link to feature work
└── Separate visibility

RECOMMENDED APPROACH:
─────────────────────────────────────
Main backlog with label:
├── Debt visible alongside features
├── Forces trade-off conversations
├── Doesn't get forgotten
├── PO sees full picture
└── Team capacity includes debt

TASK STRUCTURE:
─────────────────────────────────────
Title: [DEBT] Legacy authentication system
Description: (Use template from above)
Labels: tech-debt, security, high-priority
Story Points: 21 (large effort)
Links: Related feature work
Attachments: Architecture diagrams

CUSTOM FIELDS:
─────────────────────────────────────
├── Debt Category (dropdown)
├── Severity (Critical/High/Med/Low)
├── Estimated Cost (story points)
├── Impact Score (1-10)
├── Date Discovered
└── Enable tracking and reporting

Maintaining Documentation

Keeping Current

DEBT DOCUMENTATION MAINTENANCE
══════════════════════════════

WHEN TO DOCUMENT:
─────────────────────────────────────
├── Sprint retrospective: "What slowed us?"
├── Code review: "This should be fixed"
├── Bug investigation: "Root cause is debt"
├── Onboarding: New person notices issues
├── Architecture review: Problems surface
└── Capture when discovered

REGULAR REVIEW:
─────────────────────────────────────
Quarterly Tech Debt Review:
├── Review all documented debt
├── Still relevant? Update or close
├── Severity changed? Adjust
├── Partially addressed? Update status
├── New debt discovered? Add it
└── Keep documentation fresh

GROOMING DEBT:
─────────────────────────────────────
Include debt in backlog grooming:
├── Review high-priority debt
├── Refine effort estimates
├── Identify opportunities
├── Bundle with related features
└── Keep ready for sprint

CLOSING DEBT:
─────────────────────────────────────
When debt is addressed:
├── Document what was done
├── Note actual effort (vs estimate)
├── Link to PRs/commits
├── Lessons learned
├── Close the item
└── Celebrate!

DEBT METRICS:
─────────────────────────────────────
Track over time:
├── Total debt items
├── New debt added per quarter
├── Debt addressed per quarter
├── Debt by category
├── Age of oldest debt
└── Trend: Getting better or worse?

Communicating Debt

Stakeholder Communication

COMMUNICATING DEBT TO STAKEHOLDERS
══════════════════════════════════

MAKE IT VISIBLE:
─────────────────────────────────────
Dashboard widget:
┌─────────────────────────────────────┐
│  Technical Debt Summary            │
├─────────────────────────────────────┤
│  Total Items: 47                   │
│  Critical: 2  High: 8  Med: 37     │
│  Est. Effort: 89 story points      │
│  Added this Q: 12                  │
│  Addressed this Q: 7               │
│  Trend: ⚠️ Growing                 │
└─────────────────────────────────────┘

SPEAK BUSINESS LANGUAGE:
─────────────────────────────────────
Instead of: "Auth system needs refactoring"

Say: "Our login system is 3 years old.
Each new feature takes 2 extra days.
Security review flagged 4 concerns.
$30K to fix now, vs unknown cost later."

QUANTIFY IMPACT:
─────────────────────────────────────
├── "Losing 10 dev hours per sprint"
├── "3 bugs per month from this code"
├── "Onboarding takes 2 weeks longer"
├── "Can't add feature X without this"
└── Numbers make it real

PROPOSE TRADE-OFFS:
─────────────────────────────────────
"We can either:
A) Ship 2 features this quarter + no debt work
B) Ship 1 feature + address critical debt

Option B reduces ongoing friction
and enables faster Q4."

Let stakeholders make informed choices.

Best Practices

For Debt Documentation

1. Capture when discovered — Don't lose it
2. Quantify impact — Numbers matter
3. Regular review — Keep current
4. Single backlog — Compete with features
5. Communicate business impact — Speak their language

Anti-Patterns

DEBT DOCUMENTATION MISTAKES:
✗ Undocumented debt
✗ Vague descriptions
✗ No effort estimate
✗ Never updating status
✗ Hidden from stakeholders
✗ Separate from main backlog
✗ No prioritization
✗ All debt same severity

Related Solutions

• Managing technical debt strategically
• Creating effective sprint backlogs
• Balancing feature development with maintenance