When it comes to instructing people on how to do something, I operate on a three-strike rule. If I have to tell anyone how to do anything more than three times in a row, I write documentation for that person.

Writing documentation for others is not as easy as it appears.

I have my own formula of sorts when writing instructional documents. It took me a while to develop the right mix of what to include and what to leave out, but for the most part it works out.

If you are in a position where it would be helpful to type up an instructional doc for someone else, here are my recommendations on how to go about it.

1. Descriptive title

The title of this article is "9 Tips On Writing Documentation For Other People". From this title, you know exactly what to expect. Your title should be as informative for whatever you’re instructing your reader to do in your doc.

It is okay to go with long titles for instructional docs, by the way. However I would try to keep it under 15 words.

2. Pictures

Pictures always work. You’re probably saying to yourself "Well, duh, I knew that part.." Yes, you did. But you’d be surprised at how many people don’t bother – especially when the doc needs them.

If for example you were writing about how to change sparkplugs on a 1987 Ford Escort, yes the pictures would absolutely have to be there to assist the reader in understanding what the words mean.

This document doesn’t need any image examples because it’s purely about writing style.

3. Sections

You are reading section 3 at the moment. It’s easy to follow and understand; this is why you use sections in the first place.

4. Make section titles/breaks obvious

Each section in this doc is in bold text, making it easy to differentiate one from the other.

If you want to make it even more obvious, you can make your section titles a different color and/or italicized. This may seem like a bit of overkill, however one can never be too obvious when writing instructional docs.

5. Write a short introduction on the assumption the reader knows next to nothing about the material contained within.

Copying myself from above:

"If you are in a position where it would be helpful to type up an instructional doc for someone else, here are my recommendations on how to go about it."

If for whatever reason the reader did not understand the title, the short introduction copied above reinforces what it is again. Consider the short introduction to be a longer, more descriptive title.

6. Assume the reader knows next to nothing but not absolutely nothing.

It is incorrect to assume the reader knows absolutely nothing because you’ll never get started. For example, I know you, the reader, know how to use a word processor application like Word or OpenOffice Writer – so it is not necessary for me to instruct you how to do that. Furthermore if I actually did take the time to explain it, that goes against the title of what this article is actually about.

7. Describe steps in ridiculously simplistic terms with cautionary notes (if necessary).

If I were writing a doc explaining how to change a light bulb, this is how it would go:

1. Turn off the light so it is no longer illuminated.
2. Wait 5 minutes until the bulb has cooled down.
3. Gently grasp the TOP of the light bulb and turn counter-clockwise.
4. Continue to turn until light bulb becomes loose enough to remove.
5. Take new light blub, insert into socket and turn clockwise.
6. Continue to turn clockwise until bulb has a snug fit. NOTE: Do not overturn the bulb as it will break.
7. Turn on the light.

Yes, you probably chuckled at that, thinking, "What fool wouldn’t know how to change a light bulb and need instructions like that?"

There are plenty of fools to go around, trust me on that one.

If I did not instruct the reader to turn off the light bulb first, said moron would grab the bulb while illuminated, still piping hot and burn himself.

If I did not instruct to wait until the bulb cooled down, same result. Moron burns himself.

If I did not instruct to grasp the top, moron will grasp the bottom.

The reason you say "clockwise" and "counter-clockwise" is because there are many people who literally don’t know their right from their left – but DO know what clockwise/counter-clockwise means. I’m not joking. If I said "twist to the left", it’s a guarantee someone would twist to the right and break the bulb.

The "NOTE" part is a warning, and if not said, someone will twist in the bulb too tightly and break it.

8. Use ordered/unordered lists to emphasize steps/points.

This is an unordered list:

• Item 1
• Item 2
• Item 3

Most people know this simply as a bulleted list. It gives indentation to each item and makes them stick out. This is good for listing items you’d need (such as when writing a recipe).

This is an ordered list:

1. Read PCMech.
2. Become enlightened from reading the fountain of knowledge herein.
3. Tell your friends.
4. Have their friends tell their friends.
5. Increase Dave’s chances of world domination.

or..

1. Take computer.
2. Put under the wheel of your car.
3. Drive over computer.
4. Feel satisfaction.
5. Throw computer in dumpster.
6. Buy new computer.
7. Feel crappy you had to buy yet another computer.
8. Repeat process every 3 years.
9. Consider switching to abacus out of frustration.

It’s either 1, 2, 3, etc. or A, B, C, etc. It says "this is the order of the things you’re supposed to do".

9. Try to keep it all on one page.

Admittedly this is tough sometimes. But if you can, keep all instructions on a single page while keeping the text legible (meaning not to make it too small).

Got instructional doc writing tips of your own?

Chime in with a comment or two.

I received some CD-RW (that’s Read/Write by the way) blank discs because I ran out of my standard CD-R’s and needed to burn some traditional audio CDs (yes, some people still do this). These happened to be Memorex CD-RWs.

I pop in the disc and no matter what burner program I use (Nero, WinAMP, etc.), the maximum write speed is 4x. I’m not kidding. 4x.

To give you an indication of how slow that is, if you push a full CD of music (traditional audio, not MP3 files), it takes close to 30 minutes for the job to complete.

I was informed that the discs were bought in a 50-pack bulk and they were dirt cheap. Well, yeah, now I know why they were so cheap. 4x max write? Jeez!

To note: CD-RW discs typically do have slower max-write speeds, but I was expecting 10x for a RW, not 4x. Yes, 10x is still dirt slow but at least tolerable (somewhat).

Earlier today I bought a 30-pack of good ol’ Memorex CD-Rs. Those have a max-write speed of 40x.

Much better.

The moral of this story: Watch yourself when you buy those big 50-packs of optical media. If the maximum write speed is slow, all the savings are gone in wasted time waiting for the @#*&! disc to finish a write.