Category: Skills

Posted on

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.

Posted on

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.

Posted on

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.

Posted on

Do Your Magic!

Charles R. Crawley

By title at the avionics company where I work, I am a technical writer, but by function I am really a technical editor. And the engineers at my company often see me as a magician. They bring documents to me and ask me to do my magic on them.

Based on a posting on our Wiki, “Understanding the Value of a Technical Editor”, I would like to point out a few indicators about our worth and magical appeal.

First, my company is getting its money’s worth. I don’t know how the economic recession is affecting you, but it’s about to make my hands fall off. In less than half a year, the other technical writer and I have produced almost as many pages as we did IN THE ENTIRE LAST YEAR (emphasis added). Working harder (albeit, smarter) seems to be our alternative to hiring another writer.

Second, we are the masters of the documentation system that controls our documents. While I never intended to be a database administrator, it is in fact what I have become. We understand and control (to a certain extent) the review cycle better than anyone else. Engineers and managers always come to us to find out where something is “stuck.”

Third, we provide a level of quality control that is easily lost when non-writers take over the process. Inevitably, we fight over control of the Word documents (source files) and insist that engineers review Adobe Acrobat files, which are copies of the Word files. Whenever we lose control of this process, documents invariably get messed up in one way (writing) or another (formatting).

While I am thankful to still have a job, I am not happy with the amount of work we do because it has lead to a loss of focus on the actual writing. But I know that we contribute to the financial bottom line of our company. And I know that without our documents, equipment will not get certified, planes will not fly, and people will be even more unhappy with the airline system than they already are.

Also see, Understanding the Value of a Technical Editor(external link).

Posted on

Bette Frick’s Marketing Bingo

Carol Lamarche

Bette Frick’s upbeat webinar, “Marketing Bingo,” was the first Technical Editing SIG quarterly membership meeting of 2010. In her engaging presentation, Frick, the Text Doctor®, presented 25 marketing strategies that every editor can use.

The strategies ranged from passive to active techniques. Key points included:

  • the relationship between trust and branding
  • marketing as a process
  • the importance of investing in marketing
  • old and new traditions in networking

The webinar presentation was based on a bingo game. A bingo card, consisting of 25 squares representing different marketing tactics, was supplied. Webinar participants (marketing bingo players) who scored “bingo” were eligible for a prize.

The downloadable “Marketing Bingo” handout, including bingo card and accompanying notes, is currently stored in the SIG archives at http://www.stc-techedit.org/file20(external link). An audio file for this presentation will not be available.

To review the “Marketing Bingo” presentation, download the handout and see the interview with Frick below.

How is branding a “trust mark,” or how is branding related to trust?
I am almost addicted to my brands. I’ve had three Saturns (unfortunately, GM killed that brand recently). My first Saturn was so good to me, I just kept coming back for more. I’ve had this Saturn for 5 years and have never had one single repair in that time. I probably would have driven Saturns until I went into the nursing home!

I’m the same way with my HP products. I have two HP printers and an HP laptop, and I just bought a brand-new HP laptop. I trust the performance and the support.

In the same way, we independents can establish our brand. Think about what you like in the brands you are attracted to and purchase. For me, it’s not about being flashy—just the opposite. I like dependability, a good price, surprising features that I didn’t know I needed or wanted, and good support. We can provide all that to our clients. Dependability means quick turnaround of documents when possible and always a quick response to e-mail. I price my editing and my training classes fairly (not at the high end). There’s always someone less expensive and always someone who’s more expensive, but there’s never someone better! And so on … All businesses have a brand. I want to make sure mine is a positive one.

You talk about the “new business cards,” such as Web sites, social media, blogs, podcasts, and webcasts.
a) How important are these to editors?
I think these can be as important as you want them to be. For me, my blog is a great opportunity to prewrite my newsletter articles with an audience in mind; it’s different than writing in my journal. The webcasts are a way to highlight my teaching skills. For others, Twitter, Facebook, and other venues may suit their style and their businesses well.
b) Can we make it in business without these?
Sure, you can make it in business without any of the marketing tactics that I suggest. I simply couldn’t or wouldn’t give up my LinkedIn. It is too productive for me in uncovering leads into companies where I want to find work.
c) For people who aren’t familiar with producing or marketing with these, where would you suggest we start?
As a trainer, I believe the key to better performance is always—you guessed it—TRAINING! Take a local or online class about any type of marketing that you don’t understand. You’ll find it’s not so mysterious, and you’ll come away with a list of action items to make that particular method work for you.

Could you say a few words about Point 4, “Listings on others’ sites”? (It’s not explained in the notes.)
The only problem with listings on others’ sites is that if you complete the listing and sit back, waiting for the phone to ring, you’ll be disappointed. Do your best to create an attractive, persuasive, dynamic listing, and don’t count on ever getting a response. Then, when you do, BINGO! I found my book designer for my Marketing Bingo book, Greg Field, on a listserve for Boulder Writers’ Alliance (I posted a small ad). Just last week, Greg asked me to provide a reference for someone who found him through his Rocky Mountain Publisher’s Guild listing. I provided a glowing reference (Greg’s wonderful); he got the job; BINGO! He’s gotten two jobs through me through networking and listings.

Since I’m itching to get into the ground with my organic garden (and snow is predicted for this week), I’ll liken listings to gardens. You won’t get produce unless you plant seeds. A listing on someone else’s site or in a book of freelancers is a seed. You may get something green from it, but not every seed produces growth. (Not to mix metaphors, but if you went fishing without bait, you wouldn’t catch many fish, would you?) Enough with the metaphors.

In Point 23, “Be elected to leadership,” you mention that we should be careful to strategically select the organizations that we serve. What are the marks of a good fit?
It would be smart to lead a group of your peers (editors, perhaps). It surely will enhance your credibility if you succeed. It would be even smarter to provide leadership for an organization where your clients hang out. I volunteer for the Boulder Area Human Resources Association because HR managers, directors, and vice presidents appear at the meetings—and it’s those people who hire trainers.

You mentioned that editors and other technical communicators who are on a payroll often don’t think about how to get credibility or publicity, and are often the first fired during cutbacks. How can we market ourselves within our organizations?
You can use every one of the 25 Marketing Bingo tactics! You can write blogs for your organization; you can then turn the blog posts into newsletter articles. You can volunteer to work on the company Web site. You can organize, sponsor, or underwrite events. You can work at your company trade show. You can be elected to lead groups within your company’s industry. It’s all good—and it will gain you credibility and good publicity. You’ll build a brand of being the “go-to” person; you’re the one who really knows what’s happening and who’s who; you’re indispensable. Then sit back and watch your career blossom.

You plan to publish your Marketing Bingo concept in a book soon. What will readers find? Why should we stay tuned?
Yes, the book is in process. I’m on the third draft, and graphic artist Greg Field is working on the design. Readers will learn more about how each Marketing Bingo tactic might work for them, and they’ll learn tips for implementing each tactic in their own business. They’ll find links to other sites for further information and tips on each tactic as well.

For me, the good news is that I have so much business this spring (through careful Marketing Bingo promotion) that I don’t really have time to devote to the book right now. This is not a bad problem to have!

Although the webinar has passed, may people who use your marketing bingo card still contact you for a free gift?
Sure, if they tell me they made “bingo” by being willing to use a tactic or actually doing it … if they get five tactics in a row, they get bingo!