Documentation (Maintenance Context)
Definition
Documentation in the maintenance context refers to all the written artifacts (requirements, design, code comments, test cases, user manuals, maintenance logs) that describe the system — and specifically, the discipline of keeping this documentation accurate and up to date as the system evolves through maintenance.
Why Documentation Is Critical During Maintenance
- Maintenance is often performed by people who did not build the original system — documentation is their primary way to understand it
- Poor/outdated documentation is one of the top reasons maintenance is difficult and expensive (see Software Maintenance topic)
- Every maintenance change should be reflected back into the documentation, or the documentation becomes progressively less trustworthy ("documentation rot")
Types of Documentation Relevant to Maintenance
1. Requirements Documentation (SRS)
- Should be updated whenever requirements change (via Adaptive/Perfective maintenance)
2. Design Documentation
- Structure Charts, Class Diagrams, DFDs — updated to reflect design changes
3. Source Code Documentation
- Comments, docstrings — updated alongside code changes (see Code Documentation, Module 3)
4. Test Documentation
- Test cases, test plans — updated as functionality changes (feeds into Regression Testing)
5. User Documentation
- User manuals, help guides — updated when user-facing behavior changes
6. Maintenance Logs / Change History
- Record of every maintenance change made: what was changed, why, by whom, when
- Critical for future maintainers to understand the system's evolution
- Often maintained via commit history (Git) + issue/ticket tracking (JIRA)
Consequences of Poor Maintenance Documentation
- Increases the time/cost of future maintenance (each maintainer has to "rediscover" undocumented behavior)
- Increases risk of introducing new bugs (not understanding side effects of undocumented dependencies)
- Contributes to the system becoming effectively "legacy" and hard to touch safely
Best Practice: "Living Documentation"
Documentation should be treated as a living artifact, updated as part of every maintenance change — not a one-time deliverable frozen at initial release.
Exam tip: Emphasize that documentation must be updated as part of every maintenance change, not just written once at the start — and that maintenance logs/change history are as important as the original SRS/design docs for long-term system health.