Includes

The word “includes” is too often used where just “are” would be better. We have brought up the use of “includes” before:

“Includes” or “including” implies that part of a list is being given, not necessarily the whole list. Saying “The group includes Apple, IBM, and Motorola” leaves open the possibility that it might also include Texaco and Happy Farmer Markets, Inc. If you want to say that Apple, IBM, and Motorola are the only members of the group, say “The group is made up of Apple, IBM, and Motorola.”

“Include,” according to old Noah Webster, means “To comprise; to comprehend; to contain.” Webster gives an example that is worth a look:

The history of England necessarily includes a portion of that of France.

Notice that what follows “includes” is not everything that is included. The history of England also necessarily includes the reign of Alfred the Great and the South Sea Bubble, but we have not mentioned these things. We are merely saying that we are going to have to talk about France as well as England, because the two countries kept spilling into each other.

Many writers automatically substitute “includes” for “are” or similarly simple words. Here is a paragraph from the Web site of a certain West Virginia conservatory, in which the writer has somehow managed to stick some form of “include” into all three sentences:

The Agriculturally Important plant category includes those that are important to most people usually because we eat them or use their products in some way. Examples include cashew, chocolate, banana, papaya, sugarcane, and coffee. Another useful plant includes the carnauba wax palm.

Let’s take each of those sentences individually. First:

The Agriculturally Important plant category includes those that are important to most people usually because we eat them or use their products in some way.

This is not a bad use of the word “includes.” The sentence gets a bit murky toward the end, and the Editor might revise it this way:

The “Agriculturally Important” plant category includes any plants that are important to people because we eat them or use their products in some way.

The Editor frankly can’t imagine any other reasons for a plant’s being “agriculturally important,” so he got rid of the “usually.” Now the next sentence:

Examples include cashew, chocolate, banana, papaya, sugarcane, and coffee.

Again, not an incorrect use of “include,” but it would be better to use a colon to avoid slipping into bureaucratic language:

Some examples: cashew, chocolate, banana, papaya, sugarcane, and coffee.

Now the third:

Another useful plant includes the carnauba wax palm.

This is so silly and wrong that, if you cannot see why it is silly and wrong, the Editor will not be able to explain it to you. Rewriting it is simple:

Another useful plant is the carnauba wax palm.

Advertisements

Mixed Metaphor

mixed metaphor is a metaphor whose parts add up to a confused image. Perhaps the most famous mixed metaphor in all of English literature is in Hamlet:

…or to take arms against a sea of troubles,
and by opposing end them.

Taking arms against a sea is not a very productive use of one’s time, as old King Canute could have told us. The mixed metaphor does a very good job of conveying Hamlet’s disordered state of mind. And you can see why, for that very reason, a mixed metaphor is a very bad thing in ordinary writing. It makes you look a little crazy.

But there is a difference between a mixed metaphor and a series of metaphors.

After entering the inner sanctum, a writer for the Boston Saturday Express provided the following breathless, mixed-metaphor-laden account: “This is the capital of Bohemia; this little room is the rallying-place of the subjects of King Devilmaycare; this is the anvil from which fly the brightest scintillations of the hour; this is the womb of the best things that society has heard for many-a-day; this is the trysting-place of the most careless, witty, and jovial spirits of New York,—journalists, artists, and poets.” [Justin Martin, Rebel Souls.]

“Breathless” it may be, but this is a string of metaphors, not a mixed metaphor. “This little room is the rallying-place of the scintillations that fly from the womb of King Devilmaycare”—that would be a mixed metaphor.

Victimized by a Workshop?

Don’t Be Victimized by Identity
Theft Workshop

That was a banner in front of an accountant’s office. Yes, we can figure out, eventually, that this is advertising a workshop on how to avoid identity theft. But the Editor’s first reading was that these accountants were worried about some identity-theft workshop that was victimizing people right and left. He imagined the five-second teaser on prime-time TV: “Yet another victim of the rogue workshop, but this one fights back. Tonight at eleven.”

Remember that you don’t usually get more than a first reading. Remember that you especially don’t get a second reading when you’re hanging a banner by a busy highway.

But the Editor did give this banner a second reading, because he is more persistent than most of your readers. His second interpretation was that this was some sort of theft workshop that would teach thieves how to avoid becoming victims of identity—in other words, perhaps the meaning was “How Not to Get Caught.”

Well, we’ve enjoyed our little game of misinterpreting this banner. But if you were the one who put up this banner, hoping to lure unsuspecting passers-by to your workshop, you wanted it to be interpreted the right way. How would you have accomplished that?

The easiest way is not to make people wait for the main noun in the phrase. Give it to them right away, like this:

Workshop:
Don’t Be Victimized by Identity Theft!

Use Words Because They Mean Something

Here is a sentence that starts out to say one thing and ends up saying something completely different:

it-is-unlawful

If you’re using the hold-open latch, you can’t just wander away. That’s what we want to say here.

“Persons using dispensers with hold-open latches must remain at the refueling point during refueling” says it.

So what is “It is unlawful for” doing at the beginning of the sentence? It would be possible to begin the sentence that way, but the rest of the sentence would have to tell us what is unlawful, not what we must do: “It is unlawful for persons using dispensers with hold-open latches to leave the refueling point during refueling” would do it.

The Editor suspects that, for many people, phrases like “it is unlawful” do not mean the sum of their words. Instead, they are symbols that establish a mood. Here, what the writer was thinking was “Warning.” He might just as easily have used an upraised-hand icon or an exclamation point in a triangle, but he didn’t have those on his keyboard, so he typed “IT IS UNLAWFUL FOR” to add a certain atmosphere of warninginess at the beginning. (The Editor might have believed it was a simple mistake, except that this warning was laboriously cut out, laminated, and stuck on every pump in a large gas station near an Interstate exit. There were many opportunities to notice a typing mistake.)

Words do have meanings, and the best way to avoid misleading your readers is to be aware of the meaning of every word you write. Never accept set phrases as set.

By the way, give credit to the writer for the apology. The rule is there for a reason, but it is always good to apologize when you find yourself forced to tell people they can’t do something.

How to Recognize Absolutely Useless Information

Let’s say, hypothetically, that your car battery died. And let’s say that your car has a navigation system that requires a four-digit “Radio/Navigation Code” to reactivate it if it loses power. And let’s say you can’t find the card with the code on it. What do you do?

Not to worry! The manufacturer keeps a Web site where you can retrieve the code. All you need is your vehicle identification number and the serial number of the navigation system.

How do you find the serial number? Oh, wait—there’s a help page.

Serial Number Retrieval Help

There are several places to find your device’s serial number:

The Radio/Navigation Code and the device unit’s serial number are listed on the anti-theft ID card that comes with the vehicle. The card is usually placed in the glove box at the time of delivery.

And that’s all it says. “There are several places,” but it tells me only one place.

That’s limited information, and the way the laws of the universe are currently constituted, it will never be useful to a single sentient being. Ever. No one who has the “anti-theft ID card” with the Radio/Navigation Code on it is ever going to be on this site trying to find the serial number so as to be able to retrieve the Radio/Navigation Code. This entire page is useless information.

How would you have recognized that if you were the writer?

First, the word “several” should have set an automatic flag in your head. You should not be satisfied until you have listed the several ways, or until you have got somebody in the technical department to admit that there’s really only one way. Either the word “several” has to go, or there have to be several ways.

Second, and this is the most important rule in any technical writing, put yourself in the place of the reader. Such a simple rule, but unfortunately it’s a vague one. You have to try to imagine what the reader is doing. In this case, the reader is trying to retrieve the Radio/Navigation Code, right? Therefore, the reader does not have the card with the Radio/Navigation Code on it. You cannot, therefore, assume that the reader will be able to retrieve some other information from the same card.

If you can explain to yourself what problem the reader is trying to solve, you will almost certainly write usable instructions. (The reader is always trying to solve some problem, unless the reader is reading instruction manuals for fun.) If you do not know what problem the reader is trying to solve, then that is the problem you have to solve before you can write anything.

 

What Information Do Your Readers Need?

The Editor noticed that his scanner software had a menu with four different modes: Full Auto Mode, Office Mode, Home Mode, Professional Mode. What’s the difference? Well, a look at the help file should tell us.

Mode Selection list box

The list box at the top right of the window displays the current scanning mode and allows you to change it. Click the small arrow to the right of the list box, and then click the name of the desired mode to change the mode. You can choose from the following modes:

Full Auto Mode
Office Mode
Home Mode
Professional Mode

This is all the help file has to say about this menu. Now, what can we learn from this information?

We can learn how a drop-down list box works in computer software. But you don’t have to explain common interface tasks, like moving the pointer and choosing an item from a list, in the help file for your scanner software. In fact, it’s a bad thing to add useless information like that. Unnecessary information makes it hard to find necessary information.

So what else do we learn? We learn the names of the four modes. But we already learned them by looking at the menu, which is already there in front of us, which is why we were looking at the help file in the first place.

In other words, we have learned absolutely nothing from this help file. It was no help at all.

So what might we want to know?

We might want to know what happens if we choose one of those four modes. How is Office Mode different from Professional Mode? What happens if I use Home Mode in the office?

When you’re writing any kind of documentation, eliminate all useless information. If the reader is looking at an on/off switch, it does not help to say, “The switch has two positions. The upper position is labeled ‘ON,’ and the lower position is labeled ‘OFF.’ Placing the switch in the position labeled ‘ON’ will apply power to the device. Placing the switch in the position labeled ‘OFF’ will turn off power to the device.” All that information is plainly useless, because it is already conveyed by a mere glance at the switch.

So be ruthless in eliminating useless information. And if, when you have eliminated the useless information, you have no information left, then you have not yet given your readers the information they really want.

Don’t Avoid ‘Says’

Here’s yet another quotation from a Wikipedia article:

The SEPTA web site informs that the deterioration in the Bridgeport Viaduct was caused by erosion in the timber supports beneath the Schuylkill River.

The problem here is that “informs” is a transitive verb, meaning that it needs a direct object. It would be correct to say “informs us” or “informs readers,” but just “informs” is wrong. “Informs us,” however, would probably make some Wikipedia editor choke and rant about appropriate encyclopedic style, and “informs readers” is really awkward.

Now, the only reason the writer used “informs” was in order to avoid the word that naturally occurred to him, which was “says.” But what’s wrong with “says”? Absolutely nothing. It’s a perfectly good word that conveys exactly the idea we’re looking for. It may be common, but it’s common because it’s useful. There is no good reason to avoid it, even in the most formal prose: “Comfort, comfort my people, says your God” (Isaiah 40:1, Revised Standard Version). Avoiding it almost invariably means picking a worse word, or—as in this case—the wrong word.