In explaining my work to a translator, Gert (my main contact) neatly summed up what I do…

So the original text was…

blah-dee-blah-dee-blah-blah-dee-blah-dee-blah-blah-dee-blah-dee-blah-bl a-dee-blah-dee-blah-blah-dee-blah-dee-blah-blah-dee-blah-dee-blah-blah- dee-blah-dee-blah-blah-dee-blah-dee-blah-blah-dee-blah-dee-blah-blah-di e-blah-dee-blah-blah-dee-blah-dee-blah-blah-dee-blah-dee-blah-blah-dee- blah-dee-blah-blah-dee-blah-dee-blah-blah-dee-blah-dee-blah-

After DD’s changes it is…

To do blah-dee-blahh:

1. Blah-dee-blah blah blah

2. Blah blah blah

(With several spelling errors corrected.)

He was of course, correct.

I’ll cheerfully admit that I don’t do anything special, but what I do do, I do very quickly indeed, and from the user’s point-of-view. This makes it more cost effective to use me, than to lock some poor coder in a room with a Help Authoring Tool – and I’ve yet to see a HAT that’s both user-friendly and powerful – and a copy of Technical Writing for Dummies.

EDIT: When I told Gert about  this blog post, he said I could quote him on the following:

Working with Documentation Doctor is a pleasure, he works quickly and for a reasonable fee. If you have any doubts or questions, feel free to contact me: gert at watchftp.com

Ever click on a radio button, only to get a popup window  or – worse – a crazily whirring C: drive and a sluggish progress bar? Annoying isn’t it? More importantly, you quickly learn to distrust the GUI.

Bullets in documentation are a bit like that.

The format of instructional text, like the design of a GUI control, can either succeed or fail to suggest its function. In other words, just like software, documentation can have good or bad affordances.

Bullets look like a non-ordered list…

Prerequisites

• Full protective clothing, including goggles
• Full installation of software
• Approval from a Senior Manager
• Properly earthed power supply.

Numbers, on the other hand, look like a list of sequential instructions making up a procedure:

Startup Procedure

1. Ask everybody to leave the Reception Area.
2. Close and lock the doors behind you.
3. At the monitor, visually confirm that the Reception Area is empty.
4. Put on your protective clothing and lower your goggles.
5. Press INITIATE DEFENCE SYSTEM

Unfortunately, people often treat bullets and numbers as if they were interchangeable. Mostly, we can blame Microsoft Word. If its lists were any less stable, they’d be demolished by the local authorities under building regulations!

So, rather than fiddling with numbering schemes, the busy writer uses bullets for everything:

Prerequisites

• Full protective clothing, including goggles
• Full installation of software
• Approval from a Senior Manager
• Properly earthed power supply.

Startup Procedure

• Ask everybody to leave the Reception Area.
• Close and lock the doors behind you.
• At the monitor, visually confirm that the Reception Area is empty.
• Put on your protective clothing and lower your goggles.
• Press INITIATE DEFENCE SYSTEM

As the system operator, I am now confused.

If the Startup Procedure is a sequential procedure, then the same follows for Prerequisites.

Dutifully, I put on my full safety gear. I blunder around looking for the disks, then – fumbling with gloved fingers – install the software over the existing installation (so wiping all the data). Next I lumber off to find a Senior Manager, making a mental note to drop by stores on the way back, in order to pick up a power supply…

The fellow who gets my job (once Security have thrown me into the street), is determined not to make the same mistake. To him, bullets are always a non-ordered list!

Chuckling at his predecessor’s stupidity, the new guy quickly fulfills the Prerequisites, then comes to the Startup Procedure. Obviously, he’ll work through the instructions in the most convenient order. (Later he might number them, so he can remember the quickest way of doing things.)

So it is that he leans out of the office to lock the Reception Area, then presses the INITIATE DEFENCE SYSTEM button. While the system powers up, he struggles into his protective clothing, then – a little blind now, thanks to the glare – gropes for the intercom so he can ask the several important clients to leave the affected room. They don’t seem to hear him…

Well, persuasive language in documentation is just about as welcome as a product placement in your kitchen.

Just imagine…

You need to know if SmiteMaster600 – supposedly a “state-of-the-art security system” – is worth buying. The best way to find out is to download the software, and to then invest a precious hour of your life playing with it.

First challenge – how do you switch everything on? Well, according to the documentation….

Activation of the Main Security Features

Our skilled designers have optimized SmiteMaster600 for maximum ease-of-use, enabling you to quickly activate the main security features. Simply bring up the SmiteMaster Console, and click the Activate button.

Your first reaction is probably “Argh!” (or something less printable…). This is like having your driving instructor trying to sell you a car mid-lesson.

You just wanted to learn how to use the product! You really don’t want to waste time plowing through a sales pitch. Worse, though you now know the how, you still don’t know the why. If the rest of the documentation is like this, you’d need very good reasons to waste more time evaluating the product.

What went wrong?

In trying to persuade the reader, the author forgot that they were addressing a user!

It’s pointless trying to persuade a user that the software is “user-friendly” – they’ll decide that for themselves, based on hands-on experience.

Also, nobody actually enjoys reading documentation. So, to get people to read on, you need to include useful information. The above example does not.

How to present a feature effectively

You don’t have to do anything complicated. Just…

• Say what the feature does, and why.
• Describe how to use it.

An improved version of the SmiteMaster documentation would probably read like this….

ACTIVATING THE MAIN SECURITY FEATURES

The Main Security Features protect your installation from all known Type 9 Incursions. Since they may interfere with normal traffic, we recommend you only switch on these features during an alert (as defined by your organisation).

To activate the Main Security Features

-In the SmiteMaster Console, click Activate

You’ll note that the instruction is terse, without even a “simply…”. Since the feature really is easy-to-use, we can let it stand on its own merits. In fiction, this is known as show, don’t tell (something Andrea Nagar identifies as one of the rules of good documentation).

Not only is documentation like this easier to use. It’s also easier and faster to write!