This is Not Documentation

In a large enterprise network, one so large and complex that it takes a staff of, say, 25 or 30 sysadmins to keep it running, this statement doesn’t even come close to serving as useful documentation:

1. Kickstart CentOS. This is a standard kickstart using Cobbler.


What then?

Where is the Cobbler server?

How does one normally access it?

Who controls the administrative logins for Cobbler?

To which network or VLAN is it connected?

Is there DHCP on that network?

Where do we obtain IP addresses?

Who controls DNS?

What procedures are there for inventory control?

Do you have an exact, real-world example that can be used to guide us?

“Wow, that’s a lot of questions. Are you sure you’re a senior sysadmin? Why can’t you just do this?”

Well, I thought I was until I started reading something called documentation.

The best documentation will begin with an outline of the task or project, have a list of specific things that must be done, and also provide a real-world, step by step example of exactly what must be done to accomplish it along with enough information to educate your administrators about how and why things are done the way they are so they can make independent decisions.

Doing this may be perfectly obvious to the person who designed it, installed it, and has been maintaining it for the last ten years. But giving your otherwise experienced admins vague answers, or worse, sarcasm for not knowing what you know, will lead to frustration and alienation.