Great Technical Writing Sell Your Readers On Whats Important


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.

You Might Also Like:

Powered by Blogger.