Sustainable Operations
Documentation That People Use
Write and maintain documentation that survives staff changes.
Learning objectives
- Structure runbooks and handbooks
- Write for the reader, not for completeness
- Keep documentation current
Runbooks versus handbooks
A runbook tells an operator what to do in a specific situation: how to restart a service, how to run a restore. A handbook explains how the system works and why. Both are needed; they serve different moments.
Write for the reader
Document the procedure with the reader's screen in front of them: exact steps, expected results, and common failure points. Brevity beats completeness.
# Runbook: Restore nightly data backup
1. Stop the application.
2. Restore the latest backup using the platform's documented process.
3. Verify key metrics, then restart the application.Keep it current
Outdated documentation is worse than none. Make updates part of the change workflow and review key documents on a schedule.
Key takeaways
- Runbooks handle incidents; handbooks explain systems.
- Procedures must be executable, not aspirational.
- Documentation rots unless updating is routine.