You can stop now: Why documentation is no place for a message from our sponsor!
posted in Documentation Tips, Tips, all |
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!