Section 12.1. Document What Matters to You

12.1. 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 differentselfish. 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 you need at your fingertips. It is another opportunity to store something digitally so that it doesn't take up space in your brain. It reduces the work your brain has to do so that you can be more focused. Focus is good.

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 each repository. To make it easy to update, I recommend that you use a Wiki. If you're not familiar with Wikis, I describe them in detail in the upcoming section "Wiki Technology." For now, just remember that a Wiki is a web site that is very easy to update.

You can eliminate the fear of the repository never being done by declaring it to be a living document. Rather than something that has to be reprinted every time you make a change, you simply maintain the repository on the intranet. You'll update it any time you need to update it. "Done" doesn't mean it's complete and ready to print, it just means that the initial repository has been birthed and is ready to grow.

12.1.1. The Customer-Facing Repository

The first web site is publicly readable, and it contains IT customer documentation.

When a customer browses to your document repository, the main page should be very simple. Here's a template. Create a home page with the following headings:

How to get help

Include a few ways in a bulleted list.

How to request new services

List a few services that someone might need activated and provide a list or link for how she gets started. Some examples might be VPN access and how to request an external web space.

Policies

A bulleted list of links to the policies that you do have written, plus links to any equivalent pages for HR or Legal.

A single place to find all your written policies

With links to HR and the Legal department's equivalent pages.

This template should be sufficient for any small system administration group that doesn't have a similar web site yet. If you are an IT or CIO organization so large that you laugh at my little template, you probably have a huge home page/web site already and don't need such a template anyway. However, I'm surprised at how many CIO organizations have web sites that are missing at least one of the above items. I also find that large organizations are made up of smaller teams, each of which can benefit from its own repository.

IT policies are the rules by which users of your computers/networks live. These include security policies, service level agreements, acceptable use policies, ethics guidelines, privileged information/access guidelines, and so on. Under IT Policies, link to each written policy that you already have, whether these policies are in HTML, Word, or PDF format. If you don't have any policies, don't include this heading just yet. However, add any of the policies you think you should have to your to do list. If you are looking for inspiration on what policies to add or how to write them, read Chapter 7 (Security) and Chapter 9 (Ethics) of The Practice of System and Network Administration. I recommend starting with an acceptable use policy. If your legal department or HR maintains relevant policies, link to them. If these sections do nothing but highlight what policies you are missing, that's a good thing.

This template is only a start. Over time, you will realize things to add or changes to make.

If you have the time and resources, the next step is to improve this home page so that people will want to set it as their default web page. This will encourage people to go to your web site often and use it when they do need, for example, to refer to an IT policy. Add useful things like a Google search box, stock tickers, or company news. Set it as the default page on any new machine you install.

12.1.2. Internal IT Documentation

The second repository contains internal IT documentation: documents that are useful to you and the people on your team. These documents will contain information that is sensitive, and therefore it should be secured in some manner, possibly just by simple password protection. This repository is often a password-protected area of the other repository.

If you don't already have such a repository, here's a template:

• Vendor contacts and maintenance agreements . A link to a list of vendors and their contacts, along with maintenance contract information.

• Internal IT procedures . A list of procedures you do or want someone else to be able to do. Examples include checklists for setting up new users and cleaning up after departed ones.

• Network diagrams. Links to a simple network diagram that someone joining your group (or helping out for the day) can use as a reference. This may be a link to a page of diagrams.

Let's explore each of these a bit more.

12.1.2.1. Vendor contacts and maintenance agreements

Under Vendor Contacts, create a link to each vendor you deal with. The destination for each link should be a page for that vendor that lists the phone number of your salesperson, the support phone number, and info you will need when you call about a system problem. For example, for one vendor, I list the phone number, the items on their phone menu, and the answers to the questions that I know I'll be asked: the phone number they use to look up my profile, my maintenance contract number, etc. If a vendor has a unique maintenance contract for each piece of equipment I've bought from them, I put all that information in a table. That table also includes a link to the password-recovery procedure for that device, as well as a link to a locally cached copy of that procedure.

You might want to use some kind of server-side include feature to make one page that contains all the other pages. You can print the mega page every so often and keep a copy in your computer room for emergencies. If you're really cool, you'll write a script that will automatically print the document on the first of the month if it has changed since the previous month.

Every time I deal with a vendor, I use this page to contact them, even if the info is also in my personal address book. That way I know the page is up-to-date in the central repository. If I find it has become out-of-date, I update it right then and there.

12.1.2.2. Internal IT procedures

You'll never list every single procedure for everything you do, and you don't need to. However, my advice is that you document the tricky procedures that you don't do frequently and the procedures that you hate to do.

An example of a tricky procedure is breaking a RAID mirror, then reattaching/rebuilding it. You might "break the mirror" (i.e., detach the main disk from its mirror) before doing an OS upgrade. If the upgrade fails, you can mount the half of the mirror that wasn't upgraded. If the upgrade succeeds, you can reattach and rebuild the mirror. The commands to do all those things are usually relatively tricky. Therefore, the next time you do this kind of thing, create a web page and record the commands that you used and make notes about how you constructed the commands. In the future, you can refer to this page and the whole thing will go faster.

If there are many ways to do something but only one of them is right for your environment, document that specific way (and why it is the right way). Often a HOWTO document found on the Web or as part of a software distribution lists many ways to do something, but you've learned that only one of those is appropriate for your environment. You might want to paste the entire HOWTO document into your repository and add commentary, such as "Use option 3," "Don't do that," or "This shortcut worked on Server B, but do the long version on all other systems." Use color for your comments to make them stand out. Be sure to respect the original document's copyright!

I often create documents that are simply checklists. It's not as intimidating as writing a huge document fully describing every little detail. I don't have a knack for remembering details, so checklists have become a way of life for me. Since the repository is easy to update, other people will contribute to the document over time. It often grows into a full document.

The other procedures you should document are the ones you don't like to do. Sure, it would be nice to document everything you do, but who has the time? Instead, document the processes that you don't like because that creates the materials needed to train someone else to do those processes. I personally hate creating accounts. Even though I've automated the process as much as I can, it's still a pain. Plenty of it can't be automated, especially my checklist of things such as "Visit the customer on his first day to see whether he has any questions" and "Repeat the visit a week later as a follow-up." So I documented the command that I run that creates the account, how I test to make sure the account was created properly, and other things that have to be done when a new employee joins. It isn't War and Peace; it isn't even in paragraph form. It's just a bulleted list with some annotations. But now that it's documented, I have a hope of foisting it off on someone else. In Chapter 2, I talked about delegating. A good document repository is an excellent way to make a task easier to delegate.

Heck, that's my general strategy to getting more staff. I document all the tasks that I hate to do, which I would give to an assistant if I had one. The next time there is a hiring opportunity, I can refer to the repository for a list of what to include in the job description for my new assistant: create accounts, change backup tapes, fix common printer problems, and so on. Gosh, isn't it an amazing coincidence that those things are already well-documented and ready for someone else to take over?

Hiring opportunities are rare, but that's OK. I don't need a full-time person. When the development group hires someone to maintain the software build system, there I am with the web page of procedures and tasks that I can foist off onto him. Ain't I a stinker?

12.1.2.3. Network diagrams

Finally, include your network diagrams . Link to the ones that already exist. If you don't have any, make a simple one to start off, like a WAN diagram or a diagram that shows your LAN and the name of the major servers, and then draw a big cloud that represents all your desktop/laptop hosts. At one job, I found that I repeatedly needed to draw a particular network diagram on a nearby whiteboard to illustrate my point. (The diagram was four dots representing our four sites, the five WAN links that connected them, and an arrow to a cloud representing the Internet connection.) Adding this simple, easy-to-reproduce diagram to the repository was a quick way to get started. In 10 minutes, you should be able to create your first diagram and put it online.

True hot-blooded system administrators probably insist on Visio with photorealistic server icons and accurate-to-the-millipica placements, but that is a rat hole. Ever start drawing a diagram and suddenly realize you've spent the entire day getting it just right? There's no cheese down that hole. Spend 10 minutes, not 10 hours. I actually prefer to use tools that don't let me do supremely detailed and perfect work so that I'm forced to get the essence of what the diagram should look like and not futz with the details. I often do diagrams with PowerPoint and store the original and PDF copy in the repository.

If you really can't control the desire to draw the perfect diagram, sketch it out on a whiteboard and take a picture with a cheap digital camera; store the picture in the repository. It's fast and it works really well. (If someone complains that they should be redrawn in a more serious drawing package, make sure he has write access to the repository and tell him, "I look forward to your results.")

Also document the important data flows in the company: how does email get in and out of the company, where are your directory servers, and so on.