Monthly Archives: August 2010

Achieving Consistency Among Editors

Pat Moell

Introduction

I manage a group of editors at a software company. This topic describes how we strive to achieve consistency in editing software documentation among a group of editors both within a department and across divisions in a large company. We have a staff of 14 editors that serve five large writing departments. Our editors are excellent grammarians before they come to SAS, but they also get considerable training and mentoring in SAS specific guidelines when they join our staff. I acknowledge that it’s impossible to achieve 100% consistency across all editors, but consistency is worth striving for for several reasons.

Importance of Consistency

Consistency is necessary to enhance readability, to promote clarity, to hold a book together, to provide polish, to prevent confusion, and to establish credibility. It’s especially important for the user, who expects a certain look and feel across software and software documentation.

Technical editors strive to achieve consistency both within and across documents that they edit for a particular company style. A recognizable company style helps maintain the brand and helps users predict the organization of content. Editorial consistency also helps greatly reduce the cost of translation (one meaning for one term, for example, means that the term and definition need be translated only once per language).

Methods of Achieving Consistency

Here are some ways we strive to achieve consistency in our organization.

Well-written and well-maintained in-house style guides and style sheets
At SAS we have two different style guides within the company. The SAS Style Guide for Business is maintained by Corporate Communications and it follows the AP style. The SAS Style Guide for User Documentation follows the Chicago Manual of Style and is maintained by the Technical Editing Department. Neither style guide tries to reinvent the wheel. Our style guides are very specific to SAS and to the choices we have made. We also have style sheets with decisions appropriate to each product that we’re documenting. If there are multiple editors on a project, they each use the same style sheet and help in contributing to it.

Agreement about which reference books have primary authority
If what we’re looking for is not in the SAS Style Guide, we have a particular order we follow. We first check the Chicago Manual of Style and then the Microsoft Manual of Style for Technical Publications. Our dictionary is Merriam Webster’s Collegiate Dictionary, 10th Edition. We also have other important references we use such as the list of official SAS product names and the trademark list. We also have a term base where we check on official terminology.

Discussion and decision making among editors –establishing rules
If we’re still not sure of a decision after consulting our resources, we have several avenues to reach consensus. We have regular biweekly meetings of our staff, and we discuss items and make decisions about them at this meeting. If we need consensus earlier, we can poll the editors through e-mail. Decisions are recorded. If it’s a term that needs a definition, we can send it to the terminologist for further research and consensus. We also have a terminology review board in Editing that handles the editing decisions regarding terminology. They publish their decision to an archived e-mail site. It also goes to the editors and writers. The archived site is handy for reviewing the decisions.

Collaboration with other writers and editors within the company about which sets of guidelines to follow
As mentioned previously, we have the SAS Style Guide for User Documentation and the SAS Style Guide for Business. We are reaching different audiences, and we have agreed to edit according to what is customary for that audience. We have writers in India, in Austin, in Massachusetts, and in other places. Some of them are fully hooked into our style guides and processes and others are not because the companies have recently been bought. When we buy a company, we establish a liaison with the writing staff and educate them about our company style. Only after their software has been incorporated as part of ours and built according to our processes do we fully integrate them into our tool sets, guidelines, and processes. In many but not all cases, our department provides the editorial support for their writing staff. We also have some major products that require considerable documentation and that require several editors. These editors meet with the writers regularly to establish the style sheets, work out specific guidelines for those documents, and agree on processes.

Information models for various types of documents such as user’s guides, help topics, and administrator’s guides
We have an Information Models Team consisting of writers and editors that has reviewed the various types of documents that we produce and has provided an information model for each of these types of documents (for example, a Getting Started guide, a user’s guide, help, an administrator’s guide, or a reference document). Writers and editors are expected to follow these models when they write and edit. This helps achieve consistency within types of documents.

Peer reviews and manager reviews of edits
We also have regular manager reviews of edits so that if one editor is off track in some way, we can catch it and help provide training. From time to time we also have peer reviews of edits.

Mentoring and training of new editors in company style and global English guidelines
A mentor also reviews edits of a new editor and provides feedback so that the new editor can more quickly learn our style conventions. We also have formal training in using our style guide and in following global English guidelines. This training is provided both to new editors and to new writers and is also available as Webcast presentations. We follow the basic principles in The Global English Style Guide in an effort to make our documentation more easily translated and more consistent.

A standard company terminology, one definition per term or concept
Two of our editors are our company terminologists. They work with marketing people, with programmers in research and development, with writers, editors, Tech Support, and others to decide on one definition per term or concept. Sometimes this is not possible because different industries will use different terms for the same concept or the same term for different concepts. In those cases, we need to have multiple entries in the term base, much as a dictionary does. A standard terminology is extremely important because it helps greatly reduce the cost of translation. If a term means one thing, it can be translated once and its definition translated once and then stored in translation memory.

Editing tools with rules enforcement such as Acrocheck, grammar and spell checkers, and completeness checks
One of our best tools and one that helps us greatly with productivity is Acrocheck. One of our editors is an experienced linguistic analyst who customizes Acrocheck for our needs. Acrocheck flags grammar, spelling, and other mistakes and suggest a correct alternative. We have our writers use this tool first, and then we have the editors use it, too, when they get the documents for edit. The editors have a more detailed set of rules, especially the rules that apply sometimes and not others. We use XML in our Arbortext Editor authoring tool, and the writers cannot commit their files unless their files are in context. So this is also a help in knowing that the writer has tagged the content properly enough so that the files can be committed.

Editing for Consistency

Individual editors as they edit also edit for consistency within and across documentation sets. They check to see that the organization is consistent, the figures and captions are represented appropriately, the headings, lists, etc. are done according to the Style Guide.

Some Reasons for Not Editing Consistently

Sometimes styles change over time, and there are times when we do not try to be consistent entirely with our previous documentation. Some small examples are we changed from data as plural to data as singular and we changed the capitalization of product names in some cases. Because our doc sets are so large, we do not go back to legacy documentation to make changes. Doing so is costly and not worth the effort. Instead, we make the changes going forward. We also sometimes agree that different fields use the same concepts with different terms, and we decide to live with that. For example, some fields use terms such as table, column, row, and others use terms such as observation and variable.

Summary

Again, there is no way to make everything consistent. Editors are not always consistent with themselves let alone other editors. But there are many best practices you can put in place to improve consistency. And consistency is important, especially to maintain a recognizable brand for your company, to help the user predict and understand the organization of content, to keep writers from getting confused by different emphases and contradictory advice by different editors, and to greatly reduce translation costs.

Pat manages the Technical Editing Department at SAS Institute Inc., a global software company, in Cary, North Carolina.

A First-Timer’s Experience at the Technical Editing SIG Progression: Editing Challenges and Opportunities

Dan Riechers

As a first-time attendee of the STC Summit, I wasn’t sure how a progression worked. A helpful person at the STC information booth explained the concept.

Topic presenters simultaneously host tables in one of the conference ballrooms. Attendees join the table with the concept about which they would like to learn. Every fifteen to twenty minutes a bell rings, signaling attendees to change tables. This pattern continues for 75 minutes. All conference attendees, not just SIG members, are welcome to attend. At the Technical Editing SIG progression, I participated in four mini-sessions.

I began at Jeffrey Japp’s table, whose sign-tent read, “When Everyone is an Editor.” I thought, “OK, that sounds like my team.” Turned out Jeffrey is from Asheville, N.C., which is approximately 160 miles from my home in Raleigh, N.C. He began the session with a brief discussion about accepting criticism from colleagues with varied experience levels, using standard stylistic guidelines, reaching consensus, and choosing your battles. Participants shared anecdotes and suggestions. We discussed the advantages and disadvantages of not having a dedicated editing staff, and it was time to move on to another table.

Next up was Andrea Wenger’s “Strategies for Simplicity.” Andrea quickly reviewed technical communication editing and writing principles in sentence structure, grammar, parts of speech, punctuation, and word choice. She also provided a reference list, available on the Technical Editing SIG web site. Andrea’s handout will serve as a useful review tool for my technical writing team, which is ironically, located just 3 miles from Andrea’s in Knightdate, NC.

After a brief look at the remaining topics, I joined Patricia Moell from SAS Institue Inc., which is located in Cary, NC—only a few miles outside of Raleigh. At Pat’s table, we discussed “Achieving Consistency among Editors.” She offered best practices and advice from her experience with a team of editors. Pat’s presentation was tightly focused on consistency—when to use it, when to be flexible, and why it is important.

Finally, I joined Kathleen Mohar’s table “Section 508 Compliance—What Editors Need to Know.” My employer does some work with the federal government and this session provided a quick entry point into the topic. First, Kathleen educated us about this federal law, an amendment to the Rehabilitation Act of 1973. Section 508 requires that federal agencies’ documents are accessible and applies to most documentation paid for with federal funds. Kathleen shared some of her experience with compliance at RTI International, located in Research Triangle Park, NC—just around the corner from Raleigh. Participants related their experiences and lessons and asked questions.

In 75 minutes I was able to learn from folks who work with teams of editors and those who share editing duties among the writing team. In addition to reviewing technical communication best practices and learning new information from presenters, the participants in the mini-sessions also offered valuable tips and insights. For example, one participant offered a book reference, another offered a story about a difficult interaction with a fellow writer/editor, and another relayed her experience with Section 508 compliance.

Attending the STC Summit was an invaluable experience. The learning opportunities provide a real return on investment to my current employer, and the chance to meet fellow communicators from around the world and share a sense of camaraderie provided a renewed sense of the field. Valuable in a different way was the fact that I happened to sit at the tables of four folks from my current home state of North Carolina. Small world.

For summaries of the sessions, see the attached files below.

Section508Compliance_kathleen

WhenEveryoneIsanEditor_japp

And, for the best practices on “Achieving Consistency among Editors,” see the article:
Achieving Consistency Among Editors.

Working Effectively with Global Teams

Mary Van Brink

Introduction

At Abbott, my editing responsibilities revolve around the validation of computerized systems. The global computerized systems validation team includes members from Canada, France, Germany, Ireland, Spain, The Netherlands, and the United States.

We use a document repository system that enables us to electronically create, edit, and route documents for review and approval. This document repository system ensures that only one person has control of a document at a time from anywhere around the world. Formal change control enables the revision of documents. Some of the challenges that our global computerized systems validation team encounters are differing time zones, lack of proximity, and communication. To mitigate these problems, consider employing the following strategies:

Assignments

When you receive an assignment, repeat the request back to the person to be sure that you completely understand the goals and timelines. Follow up with an e-mail to confirm your understanding. Attempt to communicate with your authors in their native language. Try closing an e-mail or speaking phrases during a conversation in the author’s language. This endears you to them because you are attempting to communicate, even if your accent is atrocious. Prettig weekend en tot maandag. (That’s Dutch for “Have a nice weekend and talk to you next Monday.”)

Deadlines

If the deadline is approaching, send an e-mail to explain your progress and to remind the author that you are actively working on the request. If for any reason you are unable to make the deadline, contact the author immediately so you can negotiate a new deadline.

Differing Time Zones

Because global members may work across several time zones, be considerate as you coordinate meetings. Vary the meeting times to ensure that the same people aren’t always inconvenienced.

Editing

When it comes to editing, it doesn’t matter that an author has been a writer for 25 years. Everyone needs an editor. As an author, how often have you become so engrossed with the content that you don’t notice the mistakes anymore? It happens to all of us. Encourage your authors to relinquish their documents to an editor who can see the content with fresh eyes.

English as a Second Language (ESL)

English is usually the official language for global documentation. If you have ever read instructions that were written by a non-English-speaking author and then translated, you understand the problems you will encounter as you edit the work of ESL authors. You must determine the message that the author is trying to convey before you can help finalize content.

Lack of Proximity

Proximity is related to time. Be mindful that you may not be able to get an immediate response to your questions and plan accordingly.

Style Guide

Maintaining a simple style guide is a must. Post the style guide to a team site where the authors can access the content electronically. Have you ever encountered a belligerent author who is convinced that they don’t need an editor? Having a style guide to reference diffuses the situation and provides an opportunity to teach the author. It insures that there documents are as affective as possible. Did you jump out of your skin while reading the mistakes? Just checking to see if you’re paying attention!

Templates

It is vital to standardize the use of English in global documents. To that end, use boilerplate templates to aid the creation of documents. Using templates prompts the author for required information, and the documents have a consistent look and feel. One of the most difficult tasks for an editor is to perceive what’s missing. A consistent structure simplifies identifying missing information.

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.

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.