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.

Importune, Inopportune

“Importune” is a verb meaning “to request earnestly and often” (as Bailey’s Dictionary defines it). It is a word very rarely used in current writing, or at least very rarely used correctly.

“Inopportune” is an adjective meaning “unseasonable” or “coming at the wrong time.”

The Editor has lately seen these two words mixed up more than once:

Wrong example: Blaine also attended a well publicized dinner with many of New York City’s wealthiest at the lavish Delmonico’s restaurant—considered importune during the economic downturn.

“Importune” should be “inopportune.”

One Word or Two?

Do you write “login” or “log in”? “Shutdown” or “shut down”? “Payoff” or “pay off”?

The answer is that both forms are right, but in different places.

If you’re using one of these terms as a verb, then it’s two words:

How do I log in as a different user?

If you’re using it as a noun or an adjective, it’s one word:

This widget keeps track of user logins.

That’s the fourth failed login attempt in the last hour.

Here’s a paragraph that gets the distinction exactly backwards:

Wrong example: Three years after announcing the acquisition, the company has announced they will shutdown the service on April 30, 2014. The shut down means all mobile apps will cease to function and all of the hosted videos will no longer be available.

“They will shutdown” should be “they will shut down,” and “The shut down means” should be “The shutdown means”:

Corrected: Three years after announcing the acquisition, the company has announced they will shut down the service on April 30, 2014. The shutdown means all mobile apps will cease to function and all of the hosted videos will no longer be available.

Some style guides will have you use a hyphen instead of writing the term as one word. The same rules still apply:

How do I log in as a different user?

This widget keeps track of user log-ins.

That’s the fourth failed log-in attempt in the last hour.

Why bother making this distinction? Because it transcribes the distinction we automatically make in speech. When we say “they will shut down service,” we pronounce “shut down” as two words, with approximately equal accents. When we say “The shutdown means all mobile apps will cease to function,” we pronounce “shutdown” as one word, with the accent on the first syllable. This is a meaningful and helpful distinction in speech, and your writing should preserve those helpful distinctions whenever it’s possible to do so.

Don’t Be Afraid of Multiple Hyphens

Hyphens are very helpful in sorting out a sentence so that it’s easy to understand the first time through (and remember that the first time through is all you’re likely to get from your readers).

Resource intensive features such as stats tracking…

is much easier to read if you add a hyphen:

Resource-intensive features such as stats tracking…

Now it’s obvious that “resource-intensive” goes together as one adjective modifying “features.” The rules for using hyphens this way are not difficult, and the Editor will give you a brief summary soon.

Meanwhile, though, what happens if you need to modify the modifier?

Server resource-intensive features such as stats tracking…

It’s a common style rule that there should not be multiple hyphens in a row. It’s also a bad style rule, because quite clearly we need two hyphens in a row here.

Server-resource-intensive features such as stats tracking…

“Server-resource-intensive” is all one modifier for “features.” And of the three parts of that one modifier, the two most closely related are “server-resource.” The single hyphen, though, makes a group out of “resource-intensive” and leaves “server” off by itself, sulking in the corner.

If your editor insists that you may not use two hyphens in a row, then the answer is to rewrite the sentence. In doing so, you may discover that there is an even clearer way to say what you mean.

Features that use a lot of server resources, such as stats tracking,…

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.

Deem

“Deem” is one of those archaic terms that journalists fall in love with. No one uses it in casual conversation (the Editor quickly makes an exception for that man raising his hand in the fifth row, and admits that some exquisitely educated people may use it in casual conversation), and you can usually replace it with “think” or “consider.”

If you do use “deem,” remember that it is a thinking being that has to do the deeming.

He is very fond of terms that I deem archaic.

That would be a correct use of “deem.” But this sentence from a Wikipedia article about the novel Westward Ho! is wrong:

Although originally written for adults, its mixture of patriotism, sentiment and romance deemed it suitable for children, and it became a firm favourite of children’s literature.

Abstract concepts like sentiment and romance do not themselves have thoughts. (Another problem is that “Although originally written for adults” is a dangling modifier: it doesn’t refer to the subject of the sentence, which is “mixture.”) One way to correct the sentence would be to change “deemed” to “made”:

Although the novel was [thus we take care of the dangling modifier] originally written for adults, its mixture of patriotism, sentiment and romance made it suitable for children, and it became a firm favourite of children’s literature.

That does, however, remove the suggestion that the novel’s suitability for children is an opinion rather than a fact. We could use the passive voice:

Although originally written for adults, it was deemed suitable for children because of its mixture of patriotism, sentiment and romance, and it became a firm favourite of children’s literature.

If you don’t like the passive voice, though, you’re going to have to find someone to do all that deeming:

Although the novel was originally written for adults, its mixture of patriotism, sentiment and romance made Victorian readers deem it suitable for children, and it became a firm favourite of children’s literature.

But, really, the Editor thinks the sentence would be just as well off without the deeming:

Although the novel was originally written for adults, its mixture of patriotism, sentiment and romance made it a firm favourite of children’s literature.