Great Technical Writing Sell Your Readers On What S Important

Great Technical Writing: Sell Your Readers On What's Important

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 (tm) Styles

Most power users of Microsoft Word (tm) 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.

BONUS : Great Technical Writing: Tell Your Users What To Expect

OVERVIEW

In your User Documentation, you direct your Reader to perform tasks with your product. If you don't tell your Reader what to expect when performing those tasks, you will have a baffled Reader, resulting in dissatisfaction and expensive calls to technical support.

EXAMPLE: REVERSE OSMOSIS WATER FILTER

I bought and installed a Reverse Osmosis water filter. The instructions told me to fill, and then empty (the instructions foolishly used the term "dump," which would have caused the destruction of the system) the tank.

The filter had a capacity of about 100 gallons per day. Thus I expected the initial fill (4.5 gallon tank) to take less than one hour. After about an hour the tank was still filling. Worried, I called the technical support. I was told that it takes about two hours for the tank to fill.

One line in the User Documentation would have eliminated that call: "The tank initially takes 2 hours to fill." Not knowing what to expect I, and perhaps other Users, wasted the time and money to call the technical support line.

EXAMPLE: UPGRADING A ROUTER'S SOFTWARE

I had some problems with my Cable/DSL (Internet-Ethernet) router. The internal control panel made it easy to check for and download updates to the internal software. The system told me that it would take a few minutes to check for updates (good), but it did not tell me how long the update would take to perform once I downloaded the file.

Not telling the User what to expect in terms of time is a mistake. I started the update and after a few minutes of operation (was it working?) I canceled the process. I re-started it again, and decided to wait longer to see what happened. It took a few minutes longer, and successfully completed.

It would only take a simple phrase such as "the software update can take up to five minutes to complete" to reduce the User's anxiety.

PROGRESS INDICATORS (as displayed in a windowing environment) are often useless. Some go beyond 100%, others are logarithmic: they move quickly in the early processing and wait, seemingly at the end, for a long time while processing is completing. Consider making progress indicators relate to the time of operation, not number of files.

Some progress/activity indicators have nothing to do with the program they are associated with. I have used virus checkers that have abnormally terminated, yet the activity indicator kept on moving. Make sure that progress/activity indicators do reflect activity of the associated program.

FILE DOWNLOADS DO IT

Telling the User what to expect is not a new concept. If you have ever downloaded files, the download site will often tell how long the file will take to download, based upon your Internet connection.

EXAMPLE: YOUR PRODUCT'S INDICATORS

While most examples of "telling the User what to expect" deals with the time needed to complete an activity, others can be related to the indicators and performance of the product.

I have a small smart battery charger that has a red light for each of the battery positions. Unfortunately, the operation of these lights is impossible to understand, and there is no description of how they work.

Here's what happens. When you first insert the battery, the light illuminates. A short while later (the charging still has many hours to go), the light goes off. Sometime toward the end of the charging cycle the light may go on again.

This is clearly confusing to the User. The User's expectation is that when the light goes out, the charging is completed. This would result in a lot of User frustration, as Users would try to use "charged" batteries that were not charged. The developers of the battery charger should explain the operation of these displays.

THE BOTTOM LINE

Tell the Users what to expect as they use your product. Often this information is the amount of time it will take for an operation to complete. For other products, you may have to tell the User what the indicators mean.

Don't leave your document Readers confused or left to figure things out on their own. Doing so will reduce your Users' comfort with your product, and increase your technical support costs.