Posts

Posted on

Tweet Stream from the STC Summit 2010: “Hearing” What Real Technical Communicators Think

Vanessa Wilburn

A motif throughout the STC Summit 2010 was the idea of technical communicators as curators. Technical communicators pull together various content areas, select the ones of interest to their audiences, and provide that content to their users.

What’s in the #stc10 Tweet Stream?

With that in mind, I thought that the #stc10 hashtag stream could be interesting to other technical editors. (For more about hashtags, see: http://help.twitter.com/entries/49309(external link).) The #stc10 hashtag acted as a collection point for tweets about the 2010 conference. For example, while I was at the conference, I tweeted for the Technical Editing SIG and included the #stc10 hashtag.

My analysis of the #stc10 hashtag was limited to the days that the conference ran, trying to catch the gestalt of the conference in motion. But hashtags can have different “lives” before and after an event. Rochester Chapter President Ben Woelk notes, “I also think that the use of Twitter surrounding an event is very different than we’d see watching a hashtag on a regular basis. There has been some continued tweeting using the #stc10 and #stc11 tags, but there hasn’t been the content richness that occurred at the conference.”

After the conference, I waded through the #stc10 hashtag stream by using tools like Twapper, TweetDeck, the Twitter API, and Ben Woelk’s resources to collate the stream before it disappeared (although you can use Google to pull older tweet streams). Following is the result of my curation of that list—I looked for tweets that hopefully are of interest to technical editors and might give a flavor of what people were “talking” and thinking about during the conference.

After removing the chit chat, tweetups, and other content not relevant to editors, I used Wordle (http://www.wordle.net/(external link)) to analyze the content. What’s interesting is that no frequent keywords popped out (beyond obvious ones like “STC,” “2010,” and “tweet”). Of the 3,003 words, only a few words occurred in the teens, and most were below five occurrences. For example, “Interviewing” appeared 10 times, “Gentle” 12 times, and “design” 10 times.

Editorial Themes from the Tweet Stream

So what themes stood out among all those tweets and represented the “collective consciousness” of the conference?

To start, content strategy came up often and generated many retweets (definition: http://retweetist.com/howto(external link)). As editors, we are intimately enmeshed in content strategy through outline edits, templates, reuse decisions, and content modeling. The conference influenced this tweet discussion by including a track dedicated to content strategy and its advanced topics (http://www.softconference.com/stc/slist.asp?C=3145#TID11295(external link)). As Rachel Peters (twitter: @rachelhpeters) stated, “Content is the only corporate asset that companies still squander.” In other words, content is dramatically important, but still undervalued.

Another theme was usability and how it relates to technical communication. Although this theme might not seem to have a direct relationship to editing, it does demonstrate that all technical communicators, including editors, need to wear multiple hats to bring a quality information experience to our customers. As editors we help make content decisions, so usability can help.

  • “Too much usability testing looks at finding content; not enough tests the efficacy of the content.”
  • “If you create graphic-only docs, usability test to make sure they’re understandable across many people.”

Terminology drove the tweet stream as well, due in part to the keynote speaker, Erin McKean, lexicographer. Her passion about word usage created spikes in tweets during and after her talk on May 3. A couple of choice tweets summarized her points:

  • “Dictionaries are the Greatest Hits of great writers.”
  • “Dictionary editing is an elaborate hobby.”

In their session later during the conference, Linden Lab reported that the most-viewed article in the Second Life Viewer online help was the glossary. Clearly, terminology is important as newer technologies, such as virtual environments, rise in usage.

Last, social media and community enablement can help an editor analyze what customers are thinking about products, including their opinions, their own documentation, and their sentiment about the documents and the products. Reuse of content, through either user-authored content or RSS aggregation, can make editing decisions trickier as multiple content streams are incorporated into traditional documentation. For example, Ben Woelk (twitter: @bwoelk(external link)) shared, “Lessons learned Community Roundtable report. User generated vs. professional content. Repurpose content. Accept imperfections. A. Gentle.”

So if you wonder what you might find in Twitter, consider following a conference hashtag for your industry, a professional organization such as the Technical Editing SIG, or experts in the field. These new streams of information are packed with the latest off-the-cuff thinking.

For curated tweets from the STC Conference 2010, see the attached file below.

Posted on

The Technical Stylist Sees Sense

Kathy Underwood

“Rules may obviate faults, but can never confer beauties.”Samuel Johnson

Here’s a quiz for you grammar and language buffs: What grammatical principle (1) permits you to ignore syntax for the sake of sense and (2) gets you a bingo (50 extra points!) in Scrabble?

The answer is synesis (\ˈsi-nə-səs\), which Webster’s defines as follows:
a grammatical construction in which agreement or reference is according to sense rather than strict syntax (as anyone and them in “if anyone calls, tell them I am out”)

Synesis is sometimes calleda subcategory of notional agreement or notional concord (because of its following the notion of the meaning rather than the form or class of the word in question). The agreement in question is that Synesis concerns agreement between a verb and its subject or between a pronoun and its antecedent. While the practice is more common in British English, it turns up in American English more frequently than you might expect. A simple example of synesis would be “Eight years is a long time.” Here, we end up treating the notion “eight years” as a single unit, not a collection of units. In other words, we’re treating it just as we would the word “decade.”

But we more frequently follow synesis when we use certain “nouns of multitude,” such as amount, majority, bunch, group, a lot, percentage, and the like (Garner, 1998). The syntax in question most often consists of the noun of multitude plus the preposition of and a plural noun. An example would be “A small group of the swimmers were able to avoid the attacking sharks.” Conventional syntax (what Webster’s Concise Dictionary of English Usage calls “school-grammar agreement”) would tell us to match the verb to bunch, which is singular. But synesis—sense—tells us to match the verb to swimmers, even though it’s the object of a preposition.

I should note that not all usage commentators agree with the concept of synesis—even when they use it themselves. But the trend has persisted since around the tenth century (in Old English), so I think that we can count on its continuing influence. Bryan Garner has aptly characterized the phenomenon: “The problem lies just outside the realm of logic, in the genius of the language.”

But what, you may ask, do I do about the linguistic anguish caused by our having no generic third-person singular pronoun in English? When should synesis be preferred to “school-grammar”? Controversy continues over these topics. But for a thorough and helpful discussion of bias-free language and issues with pronouns, see the chapter entitled “Grammar and Usage” in The Chicago Manual of Style. I believe that it’s the closest we have to a consensus view at this time.

References

  • The Chicago Manual of Style, 16th ed. 2010. Chicago: University of Chicago Press.
  • Garner, Bryan. 1998. A Dictionary of Modern American Usage. New York: Oxford University Press.
  • Johnson, Samuel. “Prudence.” The Idler, No. 57, Saturday, May 19, 1759.(external link)
  • Merriam-Webster’s Concise Dictionary of English Usage: The Essentials of Clear Expression. 2002. Springfield, MA: Merriam-Webster, Incorporated.
Posted on

Strategies for Simplicity

Andrea Wagner

In keeping with our promise to provide an article on watercooler chats, here is a summary article of the most recent water cooler chat. This chat was held on June 9, 2010, and it focused on the strategies for simplicity. The chat was moderated by Andrea J. Wagner. Andrea is a Sr. Technical Writer at Schneider Electric in Raleigh, NC. She has 15 years’ experience in technical communication.

At the start of the chat, Andrea stated her premise that the more complicated the material, the simpler the writing style should be. Andrea also stressed that highly technical material is taxing to read, even for experts.

The Three Strategies

In the engaging chat, Andrea gave three important strategies to simplify the writing style.

  1. Shorten sentences.
  2. Use proper grammar and punctuation.
  3. Favor simple, muscular words.

Shorten sentences: Andrea stated that we could make it easier for users if we change complex sentences to compound sentences and compound sentences to simple sentences. She mentioned that long sentences and multiple clauses are more grammatically complex, so they’re more open to grammatical errors.

Use proper grammar and punctuation: The chat focused on the need to keep phrasal verbs together as well as to avoid dropping articles. Andrea indicated that using capitalization carefully prevents confusing the users and using punctuation well can make long sentences more readable.

Favor simple, muscular words: Andrea recommended the use of muscular or strong words. Strong words that do their own work without modifiers. She considered “very” the most useless word in the English language.

And, here is the link to the chat transcript:
http://www.stc-techedit.org/tiki-download_file.php?fileId=130(external link)
Also, here is the link to Andrea Wagner’s handout on the Strategies for Simplicity:
http://www.stc-techedit.org/tiki-download_file.php?fileId=124(external link)

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.