The Technical Stylist on the Battle of the Usage Guides

Kathy Underwood

In the Technical Editing Department at SAS Institute Inc. (a worldwide software company), one of the questions we often get from around the company staffers is about which is the best grammar and usage guide. We do have a standard list of style references, which includes the Chicago Manual of Style (16th edition), the Microsoft Manual of Style (3rd edition now—4th edition coming in January), the Global English Style Guide (by our own staffer, John Kohl), and Merriam-Webster’s Collegiate Dictionary (11th Edition).
Continue reading “The Technical Stylist on the Battle of the Usage Guides”

4 Lessons Learned During a Long-term Editing Gig

Avon J. Murphy

During more than 17 years as Book Review Editor for Technical Communication, I enjoyed the opportunity to learn a good deal. Much of this acquired wisdom comes down to four lessons that have made my life easier and might help those of you who decide to work on a journal such as ours.
Continue reading “4 Lessons Learned During a Long-term Editing Gig”

The Wicked Which and Other Fairy Tales

Andrea Wenger

Popular culture is filled with myths about grammar. Taught by generations of English teachers, these stories admonish little children to cling to the straight and narrow path, rather than venturing into the woods of creative communication. Some of these stories are usage guidelines rather than rules. Others are pure fantasy, the flight of some pedagogue’s imagination.

1. The Restrictive Which

Professional writers are warned to avoid the dreaded restrictive which. We’re told to use the word that as the relative pronoun when introducing a restrictive clause (one that’s essential to the meaning of the expression), and the word which when introducing a nonrestrictive clause (one that supplements the meaning). But is a restrictive which always wicked?

In one of the most famous speeches of the twentieth century, President Franklin D. Roosevelt used a restrictive which: “Yesterday, December 7, 1941—a date which will live in infamy—the United States of America was suddenly and deliberately attacked by naval and air forces of the Empire of Japan.”

Is this statement rendered less potent by the use of the word which rather than that? Hardly. The fashion of using that to signify a restrictive connotation has never been imitated in speech.

Where written and spoken communication agree is in the presence of a pause (signified in writing by a comma) before the relative pronoun in a non-restrictive connotation, and the absence of a pause (or comma) in a restrictive one. As long as you follow the rules for comma use, readers will understand your meaning—regardless of your choice of which or that.

Generally, I avoid the restrictive which, but judgment always trumps rote. I won’t write “that that I know to be true” when “that which I know to be true” sounds a hundred times better. Follow your style guide, but trust your inner voice (assuming your inner voice doesn’t sound like Charles Manson’s).

2. There’s No “Of” There

For brevity’s sake, the word “of” can be safely omitted after “all” and “both” in such expressions as “all of the time” (all the time) and “both of the writers” (both writers). However, using “of” in these expressions is perfectly grammatical.

3. Split Infinitives

It’s widely believed that verb phrases, and particularly infinitives, should not be split. This idea is nonsense. Usually, the best place for an adverb is immediately before the verb it modifies: “I wanted to completely replace my business wardrobe, but I had carelessly left my credit card at the shoe store.”

That being said, splitting an infinitive may not be the best choice, particularly if the split is long (such as with a string of adverbs or an adverbial phrase).

For the sake of parallelism, avoid splitting an infinitive when using a correlative conjunction (such as either…or): “I want to buy either pink shoes or purple shoes.” not: “I want to either buy pink shoes or purple shoes.”

4. Beginning Sentences with Conjunctions

It’s fine to begin a sentence, and even a paragraph, with a conjunction. But do so sparingly, or risk the invective of the Wizard of Oz to the Cowardly Lion: “You, my friend, are a victim of disorganized thinking!”

The real problem occurs when the conjunction introduces a fragment rather than a complete sentence. I assume that if you work as a technical communicator, you know a fragment when you see one. Occasional fragments are fine where the tone is casual or informal, but they should be avoided in instructional material.

5. Ending Sentences with Prepositions

There’s never been a time in the history of the English language when folks didn’t end sentences with prepositions. In speech, we do it all the time. Written language, to be effective, should maintain the same flow as speech. Rearranging a sentence to avoid ending it with a preposition often results in an unnatural construction that jars the reader. Follow the advice in Eats, Shoots & Leaves, Lynne Truss’s rollicking book on punctuation, and don’t write like a stupid person. (She said this specifically in reference to comma use, but it applies equally well to all elements of expression.)

6. Contractions

As you’ve probably noticed, I believe in using contractions to give prose a natural feel. That being said, I never use them in technical documentation. Maybe I’m afraid that the text will lose its ring of authority. If the document is promotional rather than instructional, a more relaxed tone may be appropriate. Follow your style guide.

7. Use of Second Person

In high school, I was taught to use one instead of you as the indefinite pronoun in written communication. But does anyone ever use this convention in speech? The Queen of England, maybe, and those who wish they were the Queen of England. For the rest of us, the second person pronoun is natural and comfortable. In technical writing, it’s mandatory.

Involve your readers by addressing them directly: “You must enter a password.” is clearer and more powerful than “A password must be entered.” or “Entry of a password is required.”.

Let’s face it: If you don’t tell a third-grader not to start a sentence with a conjunction, he’ll start every sentence with a conjunction. If you don’t tell him not to end a sentence with a preposition, he’ll end every sentence with a preposition. When your grammar-school teacher’s voice resonates in your head, admonishing you with these non-rules, remind yourself that her job was to teach illiterate children how to compose sentences—not to teach professional communicators how to write elegant prose.

Grammar is a matter of structure, while usage is a matter of style. And style depends on audience and intent. Obviously, you’ll adopt a different tone when writing an article for the Journal of the American Medical Association than when writing the next great chick lit novel. The tone of instructional material should be authoritative, but accessible. Stiff writing is dead on the page and doesn’t serve our customers.