Chapter 12. Documentation
This chapter is about how a good documentation repository can help us as system administrators, especially in our effort to manage our time better.
But first, let's talk about why we dislike, fear, and generally avoid writing documentation.
We're suspicious of anyone who asks us to document what we do because it sounds like the precursor to being fired. If we document what we do, we can be replaced. Alternatively, the request to have everything documented comes from outside our group, usually from someone who has gotten 'ISO 9001 fever' and doesn't realize that documenting processes is a means to an end, not the other way around.
It can be very difficult to start writing a document. 'Documentation' summons an intimidating image of a 1,000-page book describing everything we do, how it's done, and how things work. Where the heck would we start if we had to write that?
System administrators are often perfectionists. We could never document
Besides, there is always a line of people outside our offices requesting that we do urgent things. That's always going to trump documenting. Writing requires long stretches of uninterrupted time. No system administrator has that, right?
Lastly, geeks hate printed documents. Why kill a tree?
This chapter proposes something so different that I hate to call it documentation. Instead, we're going to make an information repository that is accessible, updatable, and useful. Best of all, it will serve our time management needs.
Document What Matters to You
In place of big ol' scary documentation , what do system administrators need? You need repositories to store the information that will help you from a time management perspective. Your boss may have her reasons for wanting you to maintain documentation, but I recommend that your inspiration be something different—selfish. Build documentation repositories that serve you and your time management needs, not the seemingly irrelevant needs of your boss or quality department. Specifically, SAs need two repositories:
Customer-facing repository . Documents that you want users of your network to have access to, such as the policies and procedures they should follow to get service.
Internal IT repository. The info you need internally to help you do your job, such as contact info for vendors, written instructions for tasks, and so on.
The first repository saves you time by making customers more self-sufficient. It deflects them away from bothering you. Why should they call you to ask a question when they could read about it? This way, they will only call you when they need clarification. Many customers prefer the self-help route simply because it saves them from embarrassment when they ask silly questions.
The second repository is useful because you make it useful. In particular, you record all the processes, procedures, and reference materials that
I suggest two repositories because one needs to be freely accessible by all customers, while the other may contain sensitive information that should be restricted for security reasons.
In these two repositories, you should accumulate:
How customers can request service or get help (possibly a simple decision tree)
A single place to find all your written policies (with links to HR and Legal's equivalent pages)
A list of vendors and their contacts, along with maintenance contact information
A list of procedures of the things you have to do a lot or want someone else to be able to do
A simple network diagram that someone joining your group (or helping out for the day) can use as a reference
You will put this information on a web site with a public area and a private area. To make it easy to start, I'll include a template for
