AIX Down Under

WHAT WOULD THEY DO WITHOUT YOU?

You're the system admin extraordinaire. You're indispensable. You're the fix-it guy for everything. You can multithread and keep a gazillion things in your head at once. No one knows what you do, but the systems simply won't run without you. You've been at the company forever and even a simple problem is a major catastrophe if they can't get in touch with you.

In short, you're a superhero.

You're also a Single Point of Failure!

If this describes you, it may I gently suggest you

Of course you're too busy. Do it anyway!

I know you're never going to get hit by the proverbial (or virtual) bus. Do it anyway!

You don't need to document it, no one is going to read it. Do it anyway!

Why?

Good documentation will:

• help you order your own thoughts
• improve your procedures
• save you time
• help you manage others' expectations, once they see how much you achieve
• highlight dependencies
• help the next guy to pick up the pieces after you leave
• cover you for when you're too tired. (Even superheroes need their sleep).

When you write about things you like doing, it deepens your understanding and makes you enjoy them a bit more. And most technical people neglect it, which gives you an edge. If you want to say something memorable at that next interview, how about: “I love doing documentation!”

“Where do I start?”

A high level, broad brush view of what you do (or ought to do) is a good starting point. For example, a flow of procedures, what you need to do every day, or every month, or every time there's a scheduled outage. You could even start with a table of contents or bullet points to jog your memory.

“I get writers' cramp”

You don't need to start with a blank page. There are plenty of templates and tools you can use. They can make your documentation more appealing to read and fun to write. Why not submit an article for developerWorks, create your own blog, or contribute to a forum?

“How much detail?”

I think it is unreasonable to expect you to write documentation for some computer illiterate person to walk in off the street and be a superstar admin like you. You don't have to document every step of every process. But you should have enough for someone who is familiar with standard procedures to pick up what is specific to your environment.

Focus on the big ticket items, such as month-end runs or backup procedures, or how/when(/if?) you patch the system. No need to put in every keystroke and screen shot, but a link to the standard online documentation is better than keeping it all in your head.

From firefighter to autopilot

If you're spending all day putting out fires, then good documentation will save you time, and lots of other people's time as. You'll be available for them instead of keeping them waiting. If you have procedures for a system reboot – with all their dependencies – well documented, you can even hand it over to someone competent (and literate) and buy yourself back some precious time. Then you can put the system a little more on autopilot.

"It's so easy, you don't need to document it"

Human beings learn things best when they proceed from what's familiar to them. If it's completely unknown, then however easy it may seem to you, it can be quite daunting to someone who's never done it before. A simple document with some screen captures may make all the difference.

Visibility

Documentation helps others to see what you're up to. That can help manage their expectations. When they see how much you do, and why you do it, they might be surprised. We've all seen resumes where people write “excellent communication skills.” It's like adding “squash” to your list of hobbies. You're not likely to miss out on the job because you haven't played squash since junior high school (unless it's part of the job spec). But plenty of technical people can be very good technically, but not quite so strong at relating what they do to others. Experience writing documentation is an important communication skill.

On that long-distant day when you leave for greener pastures, they'll know they will need a superhero to take your place, but if you leave behind some decent doco, at least they won't have to add a line to the job ad that the ability to read your mind will be looked on favourably.