July 15, 2009, 3:35 PM — Good documentation can take the form of comments in a configuration file, an attachment filed with a trouble ticket or a sheet in the sysadmin binder, but any change, addition or peculiar setting on a system should be represented somehow by a paper trail or notes in change management files for an individual system or network.
Some of the more disciplined sysadmins will say that a task isn't complete until the documentation has been done. Others will go further and say that it's not complete until someone besides you understands the documentation. Just jotting some notes on a form might not really explain what was changed and why. Make sure that someone who has had no role in a particular issue can explain what happened and what was done to correct the problem when they read the notes you leave behind.
If in solving a problem, you create a script or a step-by-step procedure, make sure that procedure can be followed by someone else. Each step should be clear and precise. You might have to explain the environment in which you were working, describe how the particular problem came to the surface, illustrate how the problem was resolved and provide a command or two that illustrates how someone can tell when the problem exists or when it has been fixed.
Good documentation is not necessarily long and detailed. In fact, too much detail can get in the way if someone later on needs to solve the same problem in a hurry and only has time for the shortest, most to-the-point answers.
A good outline for documenting a problem might include:
- What was observed
- How it affected the system or user
- What was determined to be the ultimate cause (often referred to as the "root cause")
- How the problem was resolved
- Additional details (how the problem came about or how to prevent recurrences)
The best documentation for systems maintenance is generally terse and is organized in a question-answer or problem-fix format. Task-based documentation provides specific help for specific problems. It also needs to be easy to find. It doesn't help one iota if you create and document a clear and effective method for resolving a problem and then no one -- maybe not even you -- can find what you've written when the problem reappears.
Don't be surprised if writing good documentation takes longer than just jotting whatever comes to mind. The more precise you want to be, the more time it is likely to take to get just the right words into your prose. But every bit of effort you put into being clear in describing a problem and its resolution is likely to save considerably more time when the problem reappears. I've been surprised time and time again how much time and trouble I have saved myself by leaving clear notes. When a problem resurfaces, instead of thinking "Hmm, when I have seen this before?", I'm quickly determining whether it's the same problem I had two years ago and whether the same cure is going to work. That's a much better and more satisfying scenario.
I've worked with people over the years who documented nothing out of some perverse belief that this made them indispensable and I've never seen that it actually turned out that way. I've also found that, not only has my documentation helped me time and time again, but it makes it easier for me to turn over a job to someone else when I'm ready to take on a different role.
