Writing Right with Handy Handbooks

Organizations with a well-developed documentation setup define their house style. The house style specifies use of language pertinent to the organization, which could be at variance with language used in general. A house style also points to other resources such as handbooks on writing or a standard dictionary. In this stroke of the Stylus, Rachna Ganguli introduces a couple of general-purpose handbooks that provide guidance on grammar and style. Over to Rachna…

Good technical documentation must be accurate, clear, concise, coherent, and relevant. For a technical writer, accuracy of phrasing and accuracy of technical concepts are of equal importance. You cannot choose one over the other.
Here is an example (from the Mayfield Handbook of Technical and Scientific Writing) that shows how the different qualities of technical prose work together:

This example is accurate in two ways:

When working out the bigger documentation-usability issues, there are times when you end up missing the basics of the language. You will agree that very few technical writers can demonstrate complete mastery over the semantics of English and the domain that they are writing for.

Most technical writers operate intuitively and some rely heavily on the editor's support. Therefore, while you master the domain, juggle the many hats a technical writer wears, chase deadlines, your work may lack the rigour required in technical documentation for want of guidance on language usage. But if you look around, help is at hand.

Yes, you all know about the industry-standard style guides, the corporate-standards document, the Chicago Manual, the American Heritage dictionary, and so on. There are many language resources, usually recommended by the house-style document, or informally advocated by the senior people in your organization. For example, your house-style guide could point you to resources, such as Read Me First!

When the first line of reference so recommended does not help you get out of the block, a handbook comes in handy. If your house-style guide does not recommend any specific handbook, you could refer to any of the ones described in this article. Here are some situations that might offer you some challenge:

A handbook does not get into the basics of grammar, nor does it deal with grammar comprehensively: it only touches upon areas of confusion that confront writers. It goes beyond grammar and makes recommendations to bring clarity and precision to a piece of writing.

Where a grammar book describes and explains rules, and illustrates them with bare minimum examples, a handbook focuses on pitfalls in writing, gives them names for the benefit of those who wish to pursue that esoteric discipline called grammar, and helps writers write better. You don't always need to know the names of the bones to use the skeletal system.

So what can a handbook do for you? It can answer most of your language queries. Therefore, to hone your writing skills, to verify what you are writing, to crosscheck the correctness of the editor's suggestions, your investment in a good handbook, in terms of money and your time, would pay off rich dividends.

You can choose any handbook, such as:

• Little, Brown Handbook
• St Martin's Handbook
• Harbrace College Handbook
• Mayfield Handbook of Technical and Scientific Writing

In this article, we look at what the Little, Brown Handbook and St Martin's Handbook have to offer.

The Preface to the Little, Brown Handbook says, "It has answers to the current and recurrent questions from writers." That might sound like a tall claim, but it does deliver on its promise.

The Little, Brown handbook walks you through various aspects of writing, such as:

• The writing process
• Critical thinking, reading, and writing
• Grammatical Sentences; Clear sentences; and Effective sentences
• Punctuation and Mechanics

It documents the expert's way of thinking and the recommended way of writing so that any keen writer can learn and implement the invisible knowledge.

So what are you missing?

There are hard and fast rules that you cannot violate, and there are flexible rules. The important thing is, even if you follow all the rules, effective writing may not result. For example, the following sentence is grammatically correct: "Colorless green ideas sleep furiously."

Only, it doesn't make any sense.

Learning to write is not just learning and implementing a finite set of rules. There is correctness of the writing only within a context. If content is the king - context is the kingdom. One kingdom's king is another's outcast.

St Martin's Handbook has a list of the twenty most common errors. Here is a look at some of the errors (in no particular order):

Missing comma(s) with a nonrestrictive element

• Marina, who was the president of the club, was the first to speak.
• Kristen's first doll, Malibu Barbie, was still her favorite.

Comma splice

• Joey went to the store, he needed to buy eggs.
• Joey went to the store. He needed to buy eggs.
• Joey went to the store; he needed to buy eggs.

Missing or misplaced possessive apostrophe

• Over-ambitious parents can be very harmful to a childs child's well-being.
• Ron Guidry has been one of the Yankees Yankees' most electrifying pitchers.

Incorrect shifts in tense

• Joe always laughs until she cried cries at that episode of Dynasty.
• Lucy was watching the great blue heron take off when she slips slipped and falls fell into the swamp.

Incorrect shifts in pronoun

• When one sees a painting by Georgia O'Keeffe, you are one is impressed by a sense of power and stillness.
• If we had known about the ozone layer, you we could have banned aerosol sprays years ago.

Lack of agreement between pronoun and antecedent

• Each of the puppies thrived in their its new home.
• Neither Jane nor Susan felt that they she had been treated fairly.

Unnecessary comma with a restrictive element

• People, who wanted to preserve wilderness areas, opposed the plan to privatize national parks.
• People who wanted to preserve wilderness areas opposed the plan to privatize national parks.
  
  Notice that the first sentence implies that all the people wanted to preserve wilderness and opposed the plan… whereas the second sentence implies that a restricted set of people opposed the plan.
  
  The first sentence is contextually incorrect, because if everyone wanted to preserve wilderness areas, then who prepared and proposed the plan to privatize national parks? Hence, the set of people who opposed the plan must be restricted.
  
  You get the idea.

Dangling or misplaced modifier

• They could see the eagles swooping and diving using binoculars.
  Who was wearing the binoculars-the eagles? [Using binoculars, they could…]
  
• He had decided he wanted to be a doctor when he was ten years old.
  What kind of a doctor could he be at age ten? [This is contextually inapt; better: When he was ten years old, he had decided…]

The list in St Martin's is based on extensive research of native English speakers. The single largest category of errors was the ubiquitous spelling mistake, a factor of more than three to one.

Notice that in the examples quoted above, the guidance has to do with clarity, precision and contextual awareness - rather than strict application of grammatical rules. To take an example, one could obstinately argue that some child prodigies (say, Doogie Howser MD) become doctors very young.

How to use a Handbook
A handbook is a reference book for the most part. Go through it a few times to make your mental map of its layout. You don't have to read it from cover to cover, you don't have to absorb all of it: the idea is to get acquainted with it enough to know where to look for guidance when you want the handbook's judgment on a sentence you wrote.

So armed with a good handbook, you can create a good and accurate document. You will learn (or maybe relearn!) the semantics and rules of the language. The handbook is your one-stop-shop for getting answers to all sorts of writing related issues. So, check out these links and get your personal copies, you won't regret this investment.

References
http://www.imoat.net/handbook/home.htm
http://bcs.bedfordstmartins.com/smhandbook/default.asp
http://wps.ablongman.com/long_fowler_lbh_9
http://ace.acadiau.ca/english/grammar/comma.htm
http://wps.ablongman.com/long_fowler_lbh_9/0,7987,822588-,00.html

_____________________________________________________

STC India | Home | Contact Us

Copyright © 2006 India Chapter STC. All rights reserved.