Useful IT Documentation
The goal of any documentation is to help people. “Good” documentation is useful. “Bad” documentation confuses readers and might contribute to physically harming people or damaging equipment.
Other definitions or classifications might be used, but here are some common types of content structure:
Narrative: A traditional documentation approach, such as system descriptions and learning tutorials.
Reference: Such as component lists, glossaries, and frequently asked questions (FAQs).
Task: Common with procedures, user guides, how-tos, and troubleshooting guidelines.
Important with such projects is consistency. Often this is resolved with a style guide. Style guides might be formal or informal. Many content management systems support presentation style attributes that satisfy the basic intent of a style guide, but usually a style guide addresses many more additional issues.
Included with consistency is terminology. Do not call a physical connection a jack in one place and a port in another place — use the technically correct term as applicable.
Suppose writing about a server (virtual or hardware) that provides a specific service. What should be documented?
Possibly something like this:
- A system description.
- Information about configurations.
- Information about alerts and notifications.
- A list of related task procedures.
- A list of disaster recovery procedures.
A common debate about documentation is who is the target audience?
Writing for an experienced professional tends to presume understanding many terms, phrases, and processes, but a less knowledgeable person often needs that information explained.
This type of audience analysis is called skill of the craft. Common in such environments is expected minimal knowledge and training that allows writing with such a presumption. Presumptions are starting points only and not written in stone. Keep in mind that skilled people sometime perform certain tasks only infrequently. All people are creatures of limited knowledge and people tend to forget and get rusty. Additional information in the documentation helps skilled people too.
When in doubt, regardless of subject matter expert (SME) egos, is write to the lowest common denominator. Typically that means the newest support person or technician, somebody who is not yet familiar with the system or work flows and needs guidance to learn. Some SMEs “loathe” that kind of detail, but in a disaster that kind of detail will be much welcomed by a less experienced person stuck working the weekend rotation for the first time.
Murphy’s Law: “Anything that can go wrong will go wrong.” Finagle’s Law: “Anything that can go wrong, will — at the worst possible moment.” O’Toole’s Corollary of Finagle’s Law: “The perversity of the universe tends towards a maximum.” Often that means when the proverbial poop hits the fan, the event will happen when the SME is on vacation or intoxicated on a Saturday night. Good documentation will help anybody faced with resolving the dilemma and avoid post traumatic stress disorder.
Be sure to regularly review all documentation. Otherwise good documentation has a nasty way of becoming bad documentation.
Posted: Category: Usability Tagged: Tech Writing
Next: Dramatic Wireless Improvement
Previous: The shuf Command