Modern System Administration

Chapter 9. Documentation

It was the early days of my first sysadmin job, and everything felt so new. Every step I took felt vital to system availability and performance. All of the rote sysadmin tasks I learned quickly by reading a book didn’t tell me when to use some root privileged commands. Thankfully, experienced sysadmins had adopted a culture of sharing knowledge. Our docs site was a wiki with a theme derived from the Cheapass Games card game “Give Me the Brain” (GMTB). GMTB’s basic gameplay was that you were a zombie working at a fast-food restaurant with one brain to pass around. Only one person could “have the brain” at a time. Associating the documentation to this game embedded the behaviors expected of the team, especially with the idea that your documentation was setting your future 2 a.m. zombie self up for success during an incident.

In this chapter, I want to help you think about documentation. I want you to feel enabled to adopt the practices that support quality documentation that is accurate, available, accessible, organized, and maintainable because documentation is part of the system.

Know Your Audience

People need insights into the information relevant to their responsibilities, ranging from “nuts and bolts” details of the operation of a specific system to “bird’s-eye” overviews of the activity in an overall environment.

Presenting people with relevant, accurate, and timely information helps them carry out their duties effectively. If individuals aren’t taking ...