Tag: Vol 10 No 2

Posted on

Verbs: Where the Action Is

Andrea Wenger

Verbs are the most important tool in a writer’s toolbox. They can make a sentence powerful and direct, or weak and meandering. In technical communication, verbs help us clarify who must act and when. But verb usage guidelines for descriptions differ from those for procedures. The context affects audience needs.

Properties of Verbs

Verbs have five properties:

  • voice (active and passive)
  • mood (indicative, imperative, and subjunctive)
  • tense (past, present, future, and their perfect counterparts)
  • person (first, second, and third)
  • number (singular and plural)

Chapter 5 of The Chicago Manual of Style offers a good refresher on these terms.

A verb’s number is a purely grammatical consideration—the verb must agree with the subject. The other properties, though, are a choice the writer or editor must make. In technical communication, there are good reasons to choose one over the other.

Verb Use in Procedures

Most task-based writing uses active voice, imperative mood, present tense, and second person to convey what the reader must do. People who aren’t technical communicators sometimes feel uncomfortable writing in this way. So they send us source material that reads “The door must be opened,” when they mean “Open the door.” They feel rude telling people what to do. But “Open the door” doesn’t sound rude to readers. It sounds clear. Readers like clear.

Here’s a procedure that doesn’t follow the recommended verb usage. Note that it is inherently unclear:

To remove the power plant, the operator must open the enclosure door. Then he can lift the protective cover. The captive screws securing the power plant are loosened. This will allow the power plant to be removed.

This wording raises some questions:

  • Must the operator lift the protective cover, or is this optional? (Use of the indicative rather than the imperative mood)
  • Is the protective cover too heavy for a female to lift? (Lack of gender neutrality resulting from the use of third person)
  • Are the screws already loosened, or must the operator perform this task? (Use of the passive voice)
  • Should the operator remove the power plant at this time, or should that step be performed later? (Use of the future tense)

The following wording, which uses the recommended verb properties, eliminates these questions:

”To replace the power plant, follow these steps:

  1. Open the door.
  2. Lift the protective cover.
  3. Loosen the captive screws that secure the power plant.
  4. Remove the power plant.”

 

Verb Use in Descriptions

Some technical writing is not task-based, however. When you’re writing or editing descriptions, different guidelines apply. Description may be in active or passive voice; in past, present, or future tense; and in second or third person.

Description is generally written in the indicative mood. Its purpose is to inform, not to instruct. Descriptions can appear on their own or within a procedure. Consider the following:

”Select File > Print.
The Print dialog box opens.”

The sentence “The Print dialog box opens” is not written in the imperative mood because it isn’t an instruction. Rather, it describes what the software does.

You could also use the passive voice in this case: “The Print dialog box is displayed.” In The Global English Style Guide, John R. Kohl writes, “Passive voice is appropriate when the agent of the action is unknown or unimportant.” So don’t put yourself through convolutions trying to recast a sentence just because it uses passive voice.

Present tense is not required in description. However, as Kohl writes, “Use the simplest tense that is appropriate for each context.” In technical communication, verb phrases like could have been installed and will not have been reset confuse readers and tax translators. But it’s not wrong to say You must accept the terms of use before you can continue. Despite the use of auxiliary verbs (also called modal verbs), the sentence is clear and direct.

The above example (You must accept the terms…) uses second person. In description, however, third person is more common: The X45 limit switch is a rugged device designed for use in dusty environments.
The proper use of verbs is key to good technical communication. Once the verb is right, chances are, the rest of the sentence will fall into place. If your time is limited, focus on the verbs first. Well-chosen verbs are a gift to the reader.

Andrea is a senior technical writer at Schneider Electric. She blogs about grammar, style, and other writing topics at andreajwenger.com. She can be reached at andreajwenger at gmail dot com.

Posted on

The Technical Stylist Talks About “Feemies”

Kathy Underwood

In 1986, Robert Connors and Andrea Lunsford started to research and document the most commonly found “errors” in the work of college composition students. They came up with their list of “Top 20 Errors(external link),” which informed their work on the Second Edition of the St. Martin’s Handbook, published in 1992. While concern remains that focusing on specific surface errors can distract students from larger issues such as organization and quality of argument, for the weary teacher, it’s a great boon to be able to give students a specific list of taboos.

Similarly, the weary technical editor can opt to provide a list of common errors to an equally weary and beleaguered technical writer. Of course, a corporate “top 20” list is usually a mix of common usage errors as well as departures from company-specific practices. An example would be the use of the serial comma, which is one of the many issues about which usage pundits have no true consensus.

The Department of Technical Editing at SAS uses their own locally derived list that we call “Frequently Marked Editing Issues” (affectionately known as “feemies”) to prompt both writers and editors to recognize all-too-common surface errors. To encourage compliance, the Editing Department provides all writers and editors with a little ring-bound flip book (about 4 ¼ x 5 ½) called the “SAS Style Guide Feemie Flipbook” with each “feemie” printed on one page of card stock. Each card states the usage issue and gives illustrative examples. Where appropriate, further explanation is provided and links are given. On our online SAS Style Guide, these are, of course, live links. (Our style guide, unfortunately, cannot be accessed outside our intranet.) For example, we have a long table with the American English equivalent of certain Indian English and British English terms (we standardize to American English).

Here are a few of our other top “issues”:

Issue
Choosing between and punctuating that and which
Long noun phrases (aka, “noun stacks”)
Use of that to show that a noun clause will follow
Putting relative clauses close to what they modify
Clarify what each prepositional phrase is modifying
Use of in versus on and vice versa

To me, one of the most helpful items has to do with preposition choice. It seems like everyday there’s another flavor of dialog box or window. And the usual guidelines about how to decide whether something is “in” or “on” some other thing aren’t always that helpful in cyberspace. On our style guide Web site, we add this statement: “We emulate Microsoft in our choice of prepositions to use in conjunction with components of user interfaces. “In” generally refers to a position within limits, and “on” generally refers to a position in contact with something.”

Image

Another very useful category to include on a “feemie” list is tagging. Should a given item be formatted as <code> or as <codeBlock> or have no tag at all? Particularly, if writers in your company use multiple authoring tools or are transitioning from one tool to another (SGML to XML, for example), everyone will welcome a “frequently confused” list to guide their tagging.

Do you and your colleagues maintain similar lists of “frequently encountered” errors or usage taboos in your workplace? I would be interested to hear about your experiences with this kind of document. Please write to me at kathy.underwood@sas.com.

Connors, Robert, and Andrea A. Lunsford. “Frequency of Formal Error in Current College Writing, or Ma and Pa Kettle Do Research.” College Composition and Communication, 39:4 (1988): 395-409.

Lunsford, Andrea A., and Karen J. Lunsford. “’Mistakes Are a Fact of Life’: A National Comparative Study.” College Composition and Communication, 59:4 (2008): 781-806. Available at http://bcs.bedfordstmartins.com/lunsford/PDF/Lunsford_article_Mistakes.pdf(external link).

Williams, Joseph M. “The Phenomenology of Error.” College Composition and Communication, 32:2 (1981): 152-168.

Posted on

Ins And Outs of the Technical Editing SIG Web Site

In keeping with our promise to provide an article on watercooler chats, here is a summary article of the most recent watercooler chat. This chat was held on May 12, 2010, and it focused on using the TE SIG Web site.

Two Cool Site Features

Rick Sapir, the TE SIG webmaster started out by highlighting the two “cool” items on the site.

  • Use of IRC (Internet Relay Chat) chatting system
  • Mirroring of the discussion list with the SIG website forum, tweets, and Linked In

Two Important Things To Know About Our Site

Rick also mentioned the two important things to know about our site.

  • First, just about everything and anything related to the SIG is available on our site.
  • Second, the site is not the only way to get information. Much of the information on the site is automatically syndicated to Twitter, LinkedIn, RSS, and our mailing lists.

Becoming a Site Editor

Chat participants were encouraged to use the wiki. Rick indicated that all pages on the site are wiki pages. He stated that anyone could volunteer for the role of a site editor, and it was easy to create, update, or edit pages. However, Rick mentioned that for some reason, it seemed like people were hesitant to do so. Rick felt that the hesitancy is unwarranted because it is impossible to break any content and it is very easy to undo a change on our Web site.

Getting Past Being Overwhelmed

The TE SIG Web site has certainly improved over the past two years! However, Rick commented that based on the results(external link) of a recent Web site feedback survey, it seemed like some users felt that there was so much “stuff” that they did not know where to begin. One of the opinions expressed in the chat was that a newsletter article would help.

As a follow up, this summary article indicates what you can do to navigate through the Web site more easily.

For the interesting perspectives that were exchanged on the chat, you can see the chat transcript.

Posted on

Creating a Style Guide Advisory Group

Andy Werth

Technical editors often must create and maintain a company or department style guide. Good editors know it is crucial to draw on colleagues to help determine effective style guidelines.

For example, if an editor doesn’t know what to call an unnamed button in the user interface, it may be best to ask the customer service team how they and the customers refer to the button and add this name to the style guide—a method far preferable to simply making up a name. For guidelines about how to refer to the company’s products, the marketing department might be the best source. Many groups in your company—IT, engineering, programming—can be a valuable resource as you build your style guide.

But getting thoughtful, punctual responses from colleagues about style questions can be difficult. This is especially frustrating when a document is on a tight deadline. A large company with an established documentation department may not have this problem; SMEs, or other editors, can often be queried for quick answers. However, if you’re a lone editor with few resources, you must draw on personnel throughout your company to establish effective guidelines.

In that case, you may need a Style Guide Advisory Group. In my experience, a Style Guide Advisory Group:

  • Reduces the time colleagues take to respond to your questions and increases the number of responses. (This may be because being part of a recognized group helps establish accountability.)
  • Encourages a sense of ownership in the style guide across teams, making it more likely that people will want to contribute to its success.
  • Ensures that style decisions address readers’ needs.

The following six steps will help you assemble your Style Guide Advisory Group.

Make the List

Make a list of personnel who you think would be a good fit for the group. Try to include one person from any group you depend on for product or end-user knowledge. If you’re not familiar with anyone in a particular group, ask coworkers for a recommendation.

Make the Pitch

Once you’ve made a list, approach each person. Explain why the group is important and why you think they’d be a good fit. For example, mention the high quality of their other work, their attention to detail, or their deep familiarity with many products.

Explain the time commitment honestly. Try to limit their commitment to about 15-30 minutes per week; anything more may be asking too much of people whose time is already stretched thin. Stress that most communication will be through e-mail (this can do wonders; for many, “meeting” is a dirty word). When explaining the time commitment, remember that it will probably be greater if you’re just getting the style guide off the ground.

Ask the Boss

Once they’ve expressed interest in the group, talk with their supervisor. (In some organizations, protocol may require that you speak with a supervisor before approaching their subordinate.) Emphasize the group’s value to their team. If you’re speaking with a customer service supervisor, stress that effective documents can reduce the number of calls from end users, and explain how a customer service team member will help documents achieve this effectiveness.

Once you’ve emphasized the group’s value, clearly define the time commitment. If you’ve made a persuasive case for the group, you’ll find that most supervisors will allow their team member to participate.

Put it in Writing

Once the group is assembled, send a welcome e-mail that states the group’s purpose, guidelines, and expectations. Guidelines might include specifying how they should respond to your questions. For example, should they respond only to you, or should they copy other members on their response and participate in a cross-group discussion that you moderate? Expectations might include that they respond to each question, that their response be carefully considered (a quick response that’s poorly informed is worse than no response), and that they respond by the deadline.

Put it to Work

Once your group is assembled, start submitting questions. A few guidelines:

  • Don’t bother group members with queries outside their area of expertise; not all queries must be sent to every member.
  • State your question clearly. When possible, anticipate what their answers might be and phrase the question in a multiple-choice format. This allows them to choose a letter rather than type a long response—but make it clear they don’t have to choose among the answers you’ve provided.
  • Include the day and time by which you’d like a response. It may help to add a reminder to your calendar to “close” the question.
  • When the response time is up, evaluate the answers and send your decision to everyone to whom you sent the question. Explain your reasoning. Before announcing your decision, wait until either you have a response from everyone or the due date has arrived.
  • Always thank them for their time.

Make it Better

After the group has been in place for about six weeks, send a quick survey to the members. Ask whether their expectations about the time commitment are being met and request suggestions for improvement.

Once you’ve established your Style Guide Advisory Group, you’ll likely find that the number of people who respond to your style questions increases, the time it takes to get responses decreases, and your company’s style guide—and therefore your company’s documents—are more effective.