Skip to main content

Great Technical Writing: Banish These Two Attitudes


Incomplete User Documents disappoint your Readers. Two attitudes of many Technical Writers result in incomplete User Documents. These two attitudes are:

. "Everyone Knows That", and

. "The User Can Figure It Out"

This article describes these attitudes and presents methods for overcoming them. The result is more effective User Documents and more satisfied Users.

1. "Everyone Knows That"

The "Everyone Knows That" attitude makes assumptions about your Reader's knowledge. These assumptions cause your Reader grief.

Here's an example of a possible "Everyone Knows That." Do you know this:

Tomatoes. Most of us keep them in a refrigerator. However, storing them in a refrigerator will ruin the taste and nutrition of tomatoes. Tomatoes should be stored on a kitchen counter at room temperature, until they are cut. Once cut, tomatoes should then be stored in the refrigerator.

Does everyone know that? What do you assume that everyone knows about your product?

Sometimes your User Documents have to overcome previous User experience. Everyone thinks that they know how to properly (safely) shut off a barbecue...they don't! The safe shutdown method is described in most barbecue User Documents, but it is not "advertised" (forcefully presented) in the User Documents.

It’s rarely true that "Everyone Knows That". Just because you find something to be obvious, it does not mean everyone knows that something.

Here's another example: How do you use a (combined product -- '2 in one') shampoo and hair conditioner? When shampooing, the shampoo is massaged into the scalp and immediately rinsed. When conditioning the hair, the conditioner is massaged into the hair, and remains on the hair for about two minutes. Now, what do the Users do for the combined product: rinse quickly, or let the product remain in the hair?

If you have the "Everyone Knows That" attitude when you write, you will tend to leave out needed material from your User Document. You will be doing a disservice to your Readers, and to your writing.

When in doubt whether "everyone knows something," assume that they do not. Then,

. add some text explaining the topic, or

. tell the Reader where to find information that will explain the topic

Another Caution

Be careful about assuming that just because you explained something earlier in your User Document, your Reader will remember (or even have read) that information. It is rare for Users to read product documentation from start to finish.

When in doubt, add a reference to that earlier (background) information. Tell your Reader where to find it, or provide a link to it if your document is electronic.

Here's a Thought Experiment: You are a User of products: How often do you read the product documentation from start to finish? If you always do, then ask some other people. (The great thing about this fact -- that Users do not read the documentation from start to finish -- is that it results in great flexibility in writing, formatting and editing the product documentation.)

2. "The User Can Figure It Out"

The User does not want to have to figure things out. The User is not reading a mystery novel or any other literature, where he/she wants to think about what is happening.

When someone uses your product, they are using it to meet their own needs. Your product may be central to your life, but to your Users, your product is a means to an end. And they do not want to have to decipher your product documentation.

Here's a simple example. An e-mail tells you to call someone, but the message leaves out the phone number. You are expected to find the phone number on your own. The writer probably knew the phone number, but left it out. This "information oversight" gets expensive within a company when the e-mail is sent to many employees...each looking up the phone number on his/her own.


. "everyone knows that" (because there is a "standard" date format -- there is not), and

. "the User can figure it out" (by seeing if my other dates provide clues to the format)

Don’t leave things for the User/Reader to figure out for themselves. It takes you only a few moments to include the material your Reader needs, and will save many Readers many hours in figuring things out.

Do It:

The writing literature tells you to "know your Reader." Here is where you use that knowledge to improve your writing.

Either

. find someone who is like your intended Reader, or

. "do your best" to act like your intended Reader (you can do it if you need to)

In reading and evaluating the document, look for places where

. the writing assumes that "everyone knows that"

. the writing expects the Reader to be able to "figure it out"

. the writing makes jumps that your Reader cannot follow

. the writing makes the assumption that the Reader has read and remembered the entire document

Fix these places. It only takes a few words or sentences.

Everyone will be happier.

Comments

Popular posts from this blog

Top 10 [FREE] Writing Courses on Youtube That Are Packed With Massive Value

This is a friendly reminder that the best things in life really are FREE, and that includes full spectrum writing courses on Youtube that teach you just about everything you will need to know about operating as a competent, reliable, and skilled copywriter. Sure, you could pay for courses and there's nothing wrong with that. But why not take advantage of a free opportunity? Here are  Top 20 [FREE] Writing Courses on Youtube That Are Packed With Massive Value. 1. Simple Learning's Copywriting Course In this course, writers will learn how to write write product descriptions, multiply sales, and how to influence your readers. Course contains very little fluff - only the most important principles are shared throughout the video.  2. Simplilearn's Full Course Content Marketing Tutorial For Beginners Every content writer and marketer wants that coveted #1 spot on Google. Heck, most want to get to the front page at the very least. This course is all about ranking high on Google an

How To Generate Repeat Sales With Your Self-Published Book

The most valuable thing you can collect if you are selling your book from a website when a visitor comes to your book's sales site is not their money... it's their email address and/or other contact information. If you have no clue how to create a website, do not worry about feeling intimidated. It is actually a lot easier than you think. You can also learn a lot by doing a search for a phrase at Google.com like "how to make a website" and "free html tutorial." You will find tons of very good free training that way and can learn how in no time. Anyone can learn the basics of creating a website in just one day. Ok, back to collecting your website visitors contact information. I know, I know you’re probably saying... "I'm an author. I want to write my book, sell my book and become a recognized expert. WHY do I need to get their contact information?" How To Make Money Writing Easy, 350-500 Word Web Articles If You Can Type, You

The Facts of a Writer's Life

So, you dream of becoming a famous writer? You want to get that article on paper as soon as possible and see it published. You've got great ideas for a book that you'll be starting any day now. But do you know what it's really like to lead a writer's life? Read on to find out. 1. Rejection is a part of life. Face it. You will be rejected. No matter how good you are, how well versed with the techniques, how intricately detailed. One fine day, you'll wake up and find a rejection in the mail. Don't get disheartened. It happens to all of us. 2. Rewriting will have to be done No matter how good your vocabulary, or how well-written your material, there will come a time, when one editor will ask you to rewrite your work. Take this as an encouraging sign. It just means that the editor likes your work, but needs you to work out a few details to suit his needs. 3. Deadlines have to be met Meeting deadlines is an important part of your career. Miss one deadlin