Essay Online

Overview

Our humdrum, sterile headings and writing manner do little to encourage our Users to read parts of the product documentation that would be especially beneficial for them. This article presents two real-world examples, how they fail their users, and how to correct the problems.

Not the Legal & Disclaimers

Although the Legal and Disclaimer sections of your documentation are important for the protection of your company (and protection of your company should be a primary goal in your work), this is not what we are talking about here. Instead, we are discussing the Document topics that are often overlooked, but are important to your Users.

We will look at two examples where the Document writer should push the Reader to investigate additional material. My suggestion is to “advertise” the topics, by using tempting writing, to urge the User to read the relevant topics.

A Rule of (Writing) Life

If a User knows one way to do something, he/she is hesitant to bother learning about other ways. You, as a Document writer, have to sell the Reader on the benefits of the “other” (better) way.

Example: Microsoft Word ™ Styles

Most power users of Microsoft Word ™ use “styles,” rather than manual formatting, to format their documents. New and casual Users do not know about this powerful tool (available in most word processors ). Word’s User Documentation does little to encourage the User to learn about styles.

The Word’s User Document talks about manually formatting characters, paragraphs, etc. Later in the document there is a section on “styles.” But why should the User ever read that section? Styles seem to be just another way of formatting characters, paragraphs, etc. The formatting section just told them how to do this.

Power Users know that for anything longer than a few page letter, styles provide many benefits.

Documenter: Sell the Reader on important topics! Encourage your User to read the additional material. Microsoft should have added something like this at the end of the section on manual formatting:

“We recommend that you use ’styles’ to format any documents longer than a few page letter. See Chapter XX to learn about styles.”

Example: Gas Barbecue Safe Shut Down

A Gas Barbecue User Document headline says: “How to Shut Off Your Barbecue.”

The Reader Thinks: “I know how to do this,” and doesn’t read the material.

If your Users are doing things unsafely or incorrectly then that bland headline will do nothing to help them correct their ways. Let’s try a more convincing headline for this:

“Most People Shut Off Their Barbecues Unsafely: Here’s the Correct Way”

Or even more focused:

“You Probably Shut Off Your Barbecue Unsafely: Here’s the Correct Way”

This wording sounds like you are selling a product to the User. But you are not. You are using marketing techniques to get Users to read important material.

By the way: If you have a gas barbecue, compare how the instructions tell you to shut it off, versus how you actually shut the barbeque off.

“See Also” is too Bland

Don’t fall into the trap of simply adding “See Also” sections where relevant. These are OK for telling the Reader where to find additional information, but do nothing to convince your Reader to read important additional material. If the material is of real benefit to the Reader then sell them on reading it. Compare these:

* See Also: Styles, Chapter XX

* We recommend that you use “styles” to format any documents longer than a few page letter. See Chapter XX to learn about styles.

If you were reading the User Document, which of the above two headings would get you to learn about styles? (If you gave the ‘wrong’ answer, then ask some other people;-)

The Bottom Line

By selling the Reader on what you (or your subject matter experts) consider important (beyond the legal and disclaimer statements) you are adding your knowledge to the document. In effect, you are saying, “I think you should read this topic because it may help you.” That’s a good thing to say, especially because it reflects your good attitude to your Reader.

OVERVIEW

Stop confusing your Reader with the words you use. Your Reader is trying his/her best to understand how your product works without having to figure out your writing. Here are some writing guidelines to help you stop baffling your Reader.

SAME CONCEPT: SAME WORDS

User Documents are not meant to be entertaining. Do not try to be creative, especially by using synonyms for specific concepts in your product. When you talk about a topic use the exact same wording to describe (or name) the topic everywhere in your User Document.

For example, the “Same Concept: Same Words” guideline, says that if there is a control on your product called the “Activation Button,” then everywhere you talk about that button use the term “Activation Button.”

Don’t be “creative” and use words like “Activation Control” or “Start Control” to refer to the “Activation Button.” Using the different wordings forces your Reader to have to stop and think “Is this the same thing as ‘Activation Button’?”

DIFFERENT CONCEPTS: DIFFERENT WORDS

I bought something on the Internet that had a rebate available for it. When I ordered the product, I was given a “Tracking Number” to monitor the progress of my order. This is common for orders from large companies.

When I applied for the rebate, the rebate company used the same word, “Tracking Number,” but this time it meant “their rebate tracking number.” When their website asked for “tracking number” I entered the only one that I knew, the product ordering tracking number. I was wrong; the rebate number was a totally different thing.

The Rebate number is different from the order tracking number and should have a very different name from the order tracking number.

One might argue that “the rebate company is a separate company, and must handle rebates for all sorts of sellers.” Sure, but they can use a very specific name for their rebate tracking number. They can call it the “Rebate Identification Number.” That name would not be used by any selling company to track an order. The problem is solved. No User would confuse “Tracking Number” with “Rebate Identification Number.”

QUIZ

Given the information in the previous two sections of this Article, wouldn’t it be really silly if the rebate company originally called it the “Rebate Identification Number” and then unannounced switched to calling it the “Rebate ID”? Answer: Yes, it would be very silly. The change forces the Reader to have to ask, “Is this the same thing as the ‘Rebate Identification Number’?”

It’s not that your Reader is too stupid or lazy to figure out what you mean. It’s that your Reader has better things to do than to decipher your writing.

WORDS YOUR READER DOESN’T KNOW

Jargon is the shortcut language of any industry. Make sure that if you use jargon in your User Document, you explain what it means. If the writing project can afford the bit of time, I recommend that you include a glossary in your User Document. Define all the jargon, acronyms, and words that you might use in ways your Reader might not expect. A great example of the latter are “debit” and “credit.” The common understanding of these words is exactly opposite to those in the accounting (banking) profession.

TIP: Be suspicious of any words your spelling checker identifies. Ask yourself two questions when your spelling checker identifies a misspelled word:

* Did I really spell that word incorrectly?

* If it’s spelled correctly, am I certain that my Reader knows what the word (or acronym) means? If it’s not in the spelling checker’s dictionary it might not be in your Reader’s vocabulary.

DON’T BE AMBIGUOUS

I have a notebook computer running MS Windows XP. If I am using the Media Player and I press the keys to hibernate the computer (put it into an energy-saving sleep state), something warns me that hibernating will lose my place in the video. It then asks: “Do you want to continue? Yes/No.” Continue what?: Continue hibernating, or Continue watching the video? It would only take one or two more words to remove the ambiguity.

THE BOTTOM LINE

When you revise your writing, make sure that your Reader does not have to guess what a word might mean. If you mean the same thing as another concept, use the exact same name. If you mean something different, then use as different (unique) a name as you can. Define jargon, acronyms, and any unusually used words. Eliminate ambiguity.

Your reader is uncomfortable enough having to read your User Document, instead of using your product. Don’t make things worse by using wording that makes your Reader have to work out its meaning.