How do I manage technical debt, documentation and software maintenance?
Technical debt is the future cost of shortcuts taken during delivery. Manage it like financial debt: make it visible, rank it by interest (how much it slows or endangers you), and pay it down continuously.
Maintenance practices
- Dependency hygiene — automated update pull requests, vulnerability scanning and planned upgrades before end-of-life
- Refactor under tests, in small safe steps, alongside feature work
- Documentation as a product: README and onboarding guide, architecture overview, ADRs, API reference, runbooks and post-incident notes — kept in the repository and reviewed with code
- Deprecation policy — announce, support a migration path, then remove
- Ownership — every service has a named team and on-call contact
Legacy systems are modernised incrementally (strangler pattern) rather than rewritten in one risky step.