Documentation Techniques for Sysadmins

Sysadmins famously come up with excuses to avoid writing documentation.  "The system should be self-documenting," they say; or "I don't have the time to write documentation."  There's even the "a lack of documentation gives me job security" line.  None of these arguments have any merit, according to Mike Ciavarella.  His Tuesday afternoon "Documentation Techniques for Sysadmins" focused not just on countering those excuses ("'Should be means it isn't', "You don't have the time to not document", and "Documentation shows management you're doing work."), but also on the techniques and technology to make effective documentation.

This course was of particular interest to me since I am a member of the Documentation group of the Fedora Project and have become the documentation evangelist (some might say "nag") in my group at work.  I've been in situations where the absence of useful documentation was very problematic.  Undoubtedly, most sysadmins have several such stories, so it is important to improve documentation to reduce the occurrence of these events.

I've spoken of documentation as if is a single object, but documentation has many variations.  One of the first keys when writing documentation is to consider the audience.  The style and content of a document will be different if the audience is fellow admins versus customers versus executive management.  By having a clear idea of the audience, and writing it down, the documentation will more readily meet it's intended use.

One key to writing effective documentation is to build a link between what the reader already knows and what the reader needs to know.  Comparing a concept with something already known helps the reader understand and reduces the likelihood that the documentation is dismissed out-of-hand.  Repetition is important to the retaining of information, so it is important to repeat information.  When the information is being repeated, it is important to change the phrasing.  This keeps the text from becoming too repetitive and helps capture more of the audience.

There are many other considerations when writing documentation as well.  The voice of the text can make a difference.  Passive voice is often preferred for technical documentation, but active voice is better for instructional documents.  The enlightened sysadmin also considers gender, and makes sure gender references are only used when relevant to the topic.  Treating documentation like a court case is a good idea: the burden of proof is on the writer, things that have not been previously introduced can't be mentioned, and never leave yourself open to get torn apart on cross-examination.

Once a document has been written, it is important to edit and proofread.  Editing is best done by someone who understands the material and can help re-order sections to improve understanding.  Proofreading requires a keen eye for spelling and grammar. It's not necessary that the proofreader understand the technical concepts involved.  Before an edited and proofed document is shipped, it should be placed in front of someone who is not in the target audience and not familiar with the subject.  If that person can't determine the audience, then there's likely a serious problem with the document.

Getting help with documentation is critical.  Admins must be shown how beneficial documentation is to their own work and to the organization as a whole.  Mike has suggested that documentation work be a component of regular performance evaluations.  For those not in a management position, the bribery method works well, too.  A junior admin can offer to write documentation in exchange for a senior admin explaining a process or concept.  The important thing is that everyone be involved.

This brings up the concept of collaborative documentation tools, which could be a full-day session in itself.  The important thing is to identify the requirements and select the tool or tools that best meet them.  Generally speaking, any tool should be able to handle documentation in multiple formats (e.g. digital and print).

Once the documentation is written, it's not done.  Regular evaluations of the documentation to ensure accuracy are important.  If the group doesn't do this process on it's own (and large groups rarely do), regular documentation fests are in order.  Now that documentation has been documented, go forth and write!