Are there standards/conventions used by IT technical writers?

Solution 1:

Writing is a discipline.

I've done a lot of it, and I have as much of the basics down as an untrained person can get without documentation being a top part of my job. Time has shown me what documentation I produce will actually get read, and what will go on the Shelf of Eternal TL;DR. This is in fact the number one rule of writing anything:

Know your audience.

The audience for internal IT documentation is ourselves. And sysadmins? When we reach for documentation, especially internal documentation, we're looking for:

• Locatable
• Brief
• To the point
• Gets me to where I'm going

The five paragraph explanation on the background for a system will be ignored in favor of the checklist below it, because we're in a hurry and we just need to get it done. And if the warning in there that if you do certain steps out of order it will erase all of your backups is in that skipped over block of text, perhaps it should have some attention-getting formatting on it, or maybe include that bit in the checklist too.

Process Documentation

This type of documentation is all about describing a way of doing something. It is the easiest for an untrained person to produce since mostly it's just writing down a series of steps to follow. In my experience good process documentation has the following characteristics:

• Contains a checklist.
• The checklist is on the same page as a short summary of when and why the checklist is run.
• Below the checklist, or on a linked page, is a longer document describing the theory behind the checklist and variations that may be encountered.

You want it so that there is the checklist to follow, and at least the first level of trouble-shooting steps already on the page (or one click away) should those be needed.

This is a familiar format if you've ever looked at Microsoft KB articles: summary, fixit, details, affected systems. There is a reason for that.

Troubleshooting Guides

This is trickier than Process Documentation because you have to encode decision trees into your documentation. A simple checklist will probably not suffice, but a branching checklist, one that uses links to other checklists, is quite doable. The same rules apply to this kind of documentation as process docs:

• Be brief, don't drown your reader in details.
• Be clear on what the decision points are and where to go for follow-on actions.
• Save the deep-dive technical backgrounders for the Architectural Documentation.

A troubleshooting guide can be a big Choose Your Own Adventure story, or can be a big bulleted list of everything that's gone wrong with a system and what fixed it.

Architecture Documentation

The single hardest type to produce, since it's designed to be reference material that'll only ever get referenced by new people looking to wrap their heads around this complex thing they just walked into.

Architectural documentation is the why document. It's why this system is being used and not that system, how they're connected with this other system and what made that connection work the way it did. It's the documentation you're supposed to write as soon as you know what your production config looks like, and update as changes are made.

Format wise, I have to defer to the experts on this one.

Good documentation is also more than just the template and format for them, a unified look is good and does improve readability, it also needs some other things as well.

Regular updates

Get into the habit of going over the documentation you already have to make sure it's still good. The checklist for version 1.17 may no be good for version 1.26, time to update that. Rote checklists need the most updating since even the littlest UI changes can throw the whole thing off.

Devoting 10 minutes a week to going over documentation and identifying things that need cleanup can do amazing things.

Architectural Documentation needs to be reviewed periodically by someone who knows the system. As I mentioned, these are seldom used documents but very useful when you actually do need them. You do not want the document describing how the campus print-serving cluster is wired together with NetWare when the migration to Windows happened 3 years ago.

Discoverable

This is the hardest to get right because it depends in very large part in where you're storing your documentation.

What is the thing we tell anyone who comes by ServerFault with a question?

What have you tried already?

Followed shortly by

The top hit on Google solves your problem. Maybe you should try that.

We search for our documentation, we don't go to the bookshelf. The documentation repository needs to be just as searchable as Google, or we'll just go to Google instead.

The Central Napkin Repository is a bad place for documentation, at least if it doesn't have an online index (and it won't). A simple wiki is better as most of them include at least basic text searching. A better system is one that allows tags to be searched in addition to full-text to better focus search onto target areas.

If you're working with a document repository that supports tags, standardize your tags. Just look at the ServerFault tag-list sometime to see why. Users shouldn't have to memorize the eight permutations of vmware just to find the stuff they're looking for. This will require occasional retagging efforts.