Great Technical Writing Banish These Two Attitudes

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.

My favorite pet peeve: dates. Within recent memory we​ "survived" the​ Year-2000 transition. Yet we​ still write dates sloppily. we​ use "06" for a​ year,​ instead of​ "2006." When we​ see things like "07/11/04" what is​ the​ date it​ is​ referring to? is​ it​ November 4,​ 2007,​ April 11,​ 2007,​ or​ some other permutation of​ the​ numbers. the​ standards for the​ format of​ dates vary around the​ world. This is​ an​ example of​ both assumptions:

. "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.


. 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.

Great Technical Writing Banish These Two Attitudes

Related Posts:

No comments: Comments Links DoFollow

Powered by Blogger.