Sssdirect.com - Great Technical Writing: Sell Your Readers On What's Important
OverviewOur 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.
Tags: Writing, User, Documents, Manual, Instruction, Guide, Technical Writing, Writing
'I Can Write A Book In A Weekend,' And Five Other Annoying Things Beginners Say
Since every literate person can write, most people think they can be writers. Interestingly enough, we all can speak quite well, but few of us would deem ourselves ‘speakers.' However, this prevalent belief encourages beginners to say the oddest things th
"Do I Have Writing Talent?" It's A Mistaken Question
Over the years, many people have asked me to look at their writing. "I need to know, do I have talent or not," they say. "Then I'll know if I should pursue writing or stick to accounting." Their request is seriously flawed, I'd reply.
"Don't Polish The Turd," And Other Oddball Writing Advice That Works
Even with a dozen published books to my name, I sometimes need a dose of inspiration when I sit down to write. Above my desk, I've posted a paper with various pieces of fiction-writing wisdom I've collected over the years. Some of the advice may sound odd
You're Not Done Yet: Eight Strengtheners For Your Sales Copy
Writing sales copy for a new or to-be-relaunched product takes a lot of energy and concentration. When you finish that first draft, take a rest. Then go back to what you've written with this sales copy checklist, which outlines the eight most frequent cor
Your Book Arrives From Your New York Publisher!
A large box arrives from a New York Publisher. It's here—YOUR BOOK! You hurriedly rip it open and take the first book out. There it is...YOUR NAME as the author of your first book. You forget to breathe and your heart skips a beat in excitement. You caress
Young Writers
If you are between the ages of 8 to 18 and love to write, be it short stories, plays or poems, then you are a young writer. For the writer nothing is more satisfying than finishing a story, play, poem etc. In fact some young writers decide to make it thei
Writing: Getting Started
Are you having difficulty writing? Do you find it hard to even get started? You probably already are an "acclaimed author" and don't even know it. Your emails and message board discussions are key seeds to informative and interesting web content
Writing What You Want To Write: Personal Innovation
Most of the important things in the world have been accomplished by people who have kept on trying when there seemed to be no hope at all. - Dale Carnegie Some of the special skills discussed in writing may have you feeling as if there is really no room
Writing Well For The Web
If you expect your potential clients to read the texts on your site, be especially particular about the content. Writing for the web has its own peculiarities in comparison with common publications. It is known that 79% Internet users just skip over the
Writing Twenty Novels (In Ten Easy Steps!)
During a recent telephone conversation, I mentioned having sent off the last revisions for my twentieth novel, “Great Sky Woman.” There was a silence on the other side of the phone, followed by the question “How in the world do you do that? Twenty novels!
Writing That Resume
When preparing your resume make sure the skills you list are accurately conveying your experience and knowledge in each area. It is also recommended that time be spent reviewing the skills the company is looking for in order to highlight these skills in a
Writing Success: What Does It Mean To You?
Like most creative professions the question of a qualified success in writing is not easy to concentrate into one definitive answer. Just as there are a multitude of writing styles, so too are there many examples of writing success. Examples 1. "I
Writing Style: Are You A Real Writer?
I hear it all the time from my students and at the seminars and workshops I lead. The writers that I work with are excited to work with a "real" writer. Most people define a "real" writer as one who is published. Therefore I, with thre
Writing Stories
There's nothing like writing a story. It is a truly satisfying creative process. In order to write a story that people will enjoy. You need to understand the key elements that all good writers use in stories. In this article we will explore these elements
Writing Short Articles Is Easy
Short article writing is as not as difficult as you think. No, it is not a daunting task if you know what to do. Just remember that when you write, the important thing is that you catch your reader's attention. You must make them want to read what you