Are there standards/conventions used by IT technical writers?

Question

TL:DR? Fine...here:

Short of hiring or outsourcing to a Tech Writer, are there basic standards/conventions/practices that Technical Writers employ in their trade that can be learned from in order to create proper IT documentation and maintain that documentation over time?

---

While writing various documentation for both internal IT usage and external use by our employees, it has become clear that our employees all have their own style when it comes to the documentation.

Pulling from our Quality documents and controlled documentation, IT has utilized various templates for SOPs, WI's, and various forms used for IT quality docs. These docs, while not necessarily that useful for day to day operations within IT do help employees and the company with IT HR issues, compliance, etc. and are typically well written, well defined, and follow at least the Quality dept.'s templates and documentation standards (like versioning, ECNs, etc.)

But our actual IT document writing is still lacking a true convention/standard. Some will use 3rd party tools like ScreenSteps, others simply use Word and create a simple outline like:

1. Open app
2. Click on `Start Global Thermonuclear War"
3. ...
4. Profit

Internal IT documentation is actually worse, based on whatever the employee or consultant felt was sufficient at the time to either jog their own memories or was based in their editor of choice (vi, word, excel, powerpoint, napkin, internal wiki). The problem comes when an employee leaves or is on vacation and a scramble is made to figure out even basic information. At times only the file date is an indicator of whether the data is still relevant or not.

While a simple outline, actual screenshots, or even full on HD video are all well and good, we don't have an actual IT Technical writer on staff and can't help but think we are lacking in this area.

Could we make up our own standards for our documentation along with approved templates? Yes, but why re-invent the wheel? If such standards and conventions already exist within the Technical Writer's "guild" we would be better served to follow those conventions so that our documentation is clear, concise, and professional.

To avoid being told "Google It", I did look at sites that showed some formatting practices and while this SF Q: IT Documentation Platforms helps with finding platforms and software to handle the writing, it doesn't discuss if there truly are standards within the industry.

So, short of hiring or outsourcing to a Tech Writer, are there basic standards/conventions/practices that Technical Writers employ in their trade that can be learned from in order to create proper IT documentation and maintain that documentation over time?

Answer 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.