Great Technical Writing Banish These Two Attitudes

Great Technical Writing: Banish These Two Attitudes

Overview

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.

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.

BONUS : Great Technical Writing: Beware Of Your Editor/love Your Editor

Overview

Your editor should be an integral part of your writing team. Do not think of him/her as a judge, but rather as a resource to help you in all phases of the writing project. This article will help you overcome any fear of your editor, and how to effectively use your editor during the writing process.

Beware of Your Editor

Some of the changes that an editor might suggest could make the User Document more difficult for your Reader to understand.

Improving Your Writing

Once your editor has gotten past the basic mechanical editing tasks of:

* grammar

* punctuation

* spelling

* editing to a Style Sheet,

he/she may work on "improving your writing."

Your editor may believe that one way to make the writing more interesting is to use synonyms when you refer back to something. Thus you might call something a "chip bin" in one part of your text, and your editor might suggest using a different term, such as "waste trap," later in the document. This should make your writing "more interesting."

You do not want interesting writing in your User Documents! You want clear, simple, very easy to understand writing. If you make your writing more interesting by using the synonym ("waste trap") then you force your reader to have to think about whether or not these are the same thing. I recommend that you use the exact same wording every place in your User Document where you are referring to the same thing. No synonyms here!

If your Reader wanted to be entertained or have his/her thoughts provoked, then he/she would be reading a novel.

Don't let your editor make your writing more interesting or more clever if those efforts makes the material harder for your Reader to understand.

Erudition

Another place to beware of your editor is "erudition." That is, when an editor that tries to make your User Documentation sound more formal. Other than disclaimer, legal, and safety information, the User Document should sound friendly, with a conversational tone.

For example, an editor might suggest changing contractions (such as "don't") into their more formal form ("do not"). Don't do it! Contractions are conversational and they should not be avoided.

If you think about it, most people reading the User Documentation for any product are under some form of stress:

* they either want to get on with using the product, or

* something has gone wrong.

A formal document will put the User off. The document should not be silly or flippant; however, it should provide the information that the User needs in a conversational, easily understood style. The needed information should be easy to find.

Although most word processor grammar checkers are woefully inadequate, many of these checkers can be made to provide a readability score (you may have to set an option to enable this feature). Editing should help increase the readability (indicated by a decrease in the reading grade level) of the document. If editing increases the reading grade level, ask your editor why that score has changed.

What to Do

Provide your editor with the information that will enable him/her to do the best job. Here are some things to tell your editor:

* The intended audience for the User Document

* Tell your editor that you want an informal style of User Document

* What style manual or guide to be used in editing

* Scheduling and progress of the project

* Format for sharing and editing the text (make sure the editor can read your electronic documents -- do this when you hire the editor)

(Whenever you are dealing with someone outside your organization, you must have a signed non-disclosure agreement. This is in addition to any other contractual items between the outsider and your organization.)

Get to Know Your Editor

Your editor is NOT your school teacher. In your school days, your teacher-as-editor was a judge. Your goal was to impress your teacher with your writing. You were working for a grade. Thus you may have come to fear your editor.

Change your thinking! Now, your editor is on your side. Your editor will work with you to produce the best possible writing. You will not have to worry excessively about grammar. You goal is to get the information "on paper" as clearly and completely as you can. Your editor will suggest changes to polish the text.

So don't fear your editor. Make your editor part of your writing team.

Love Your Editor

Hire Your Editor Early in the Project

Hire your editor early in the life of the project. There are at least two benefits to hiring the editor early:

* First, your editor will be prepared for the editing task. He/she will have had time to get to know the product, target audience, and your organization's style guide.

* Second, your editor can help you with your writing, as I describe below...

Let Your Editor Help You

If you run into problems about how to write something, call on your editor. Most likely your editor can provide an effective wording to get you around your block. That's one reason why you got the editor on the project early. Here's another...

A Recommendation

I recommend that you work on small pieces of the User Document, and circulate these small pieces (rough drafts) to the development team for comments. Then use their comments to improve the writing, and re-circulate the improved material. Continue this for a few cycles. I call this "Iterative, Interactive Writing." This is an effective method for writing quickly and accurately.

If you feel uncomfortable about circulating rough drafts to the product development team for review, here's a solution. Have your editor perform a quick edit of the rough draft before you circulate it for comments. Your "drafts" will look quite good, and the development team will concentrate on the content, not the wording or grammar (and comments about content are you want from the team).

The Bottom Line

Don't think of your editor as an enemy lurking at the end of your document production path. Instead, realize that your editor can be a valuable member of your writing team, and is on your side. He/she should:

* Be brought onto the writing project early

* Be kept aware of the status of the writing project

* Be used as a writing, as well as an editing, resource

TIP: It is much more enjoyable for the writer (you) to work with "marked-up" electronic documents, rather than marked-up printed documents. Investigate your word processor's "multiple reviewers" capability. To employ this capability requires that you and your editor use the same or compatible word processing software.

NOTE: I am not an editor, nor do I represent any editors. But as a writer, I value editing.