One of my regular clients is GdP Software, a Dutch-based company. They use me for localisation of web text and emails, and for documenting products such as watchFTP, a powerful tool for monitoring FTP directories and processing any uploaded files.

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

Are you shooting yourself in the foot with bullets?

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…

Read the rest of this entry »

Remember Mrs Truman in the Truman Show ?

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!