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.