Monthly Archives: June 2009

Setting Up an Editorial Review Process

Sarah Barczyk

So you want to be a technical editor. You’re well-versed in grammar, style, punctuation, and the mechanics of the English language. You know what it takes to produce a clear, concise, readable paragraph and a coherent technical document.

Subject-matter experts within your company recognize that you’re an asset and routinely seek you out for writing help and perhaps enlist your aid in editing large documents. But you know that so much more can be done. All you need is a process. It sounds so simple…

But simple it’s not. As someone who’s suffered the bumps and bruises that come along with setting up an editorial review process, I can attest to that. I can also offer a few tips for integrating the editorial review into the documentation process.

First and foremost: start small. If you work for a large company, pick a particular department or project and garner managerial support by putting together a concise proposal that outlines the advantages that an editorial review process can provide. Mention benefits such as consistency across documentation for the end user and a more polished and professional look to customer deliverables. A clean document will require less rework down the road, resulting in an overall cost savings to the company, and will improve customer satisfaction. If a customer receives a document with a high rate of errors, there is a good chance the technical content will be perceived as erroneous as well. Once you have the backing of upper management, the establishment of a process will become much easier.

Be flexible, yet firm in setting up your process. Understand that the unknown is scary (and fond reminiscences of English class probably do not exist in the minds of your technical coworkers), but stress the importance of a standard course of practice. Research the place that an editorial review will fit in your documentation workflow, and gather feedback from authors, document coordinators, and mangers. I have found that the editorial review fits best at the end of the writing process, after any technical reviews. In this placement, the author and editor can work together to resolve any last-minute language issues, and the document will have a professional and polished look and feel before manager approval. There may be instances due to time constraints when this process may have to be relaxed. Be prepared to be flexible, but do everything you can to enforce a standard process.

Expect resistance. Most nonwriters view documentation as a necessary evil. Be they doctors, architects, or engineers, the technical work comes first; documentation is simply a means to transmit knowledge. What’s important is the content. I can’t count the number of times I’ve been told, “It doesn’t have to read like a novel. It just has to make sense.”

You’re going to encounter people who view editors as formatters or spell-checkers. They don’t understand that an editor can provide consistency across company documentation. They don’t recognize that an editor can make each document more readable for the intended audience. They don’t appreciate that an editor can catch simple mistakes that have previously gone unnoticed because the author happened to be too close to the document content.

In short, you’re going to encounter people who just don’t care about the editorial review process. They’ll view it as an extra step, which means extra time and money that they’re not willing to spend. And they won’t hesitate to let you know it. Here’s where managerial support will be a great asset.

You’re also going to have to prove yourself. You must prove that you’re just as much as an expert in your area as your technical coworkers are in theirs. You need to be able to back up every edit you make with information found in style guides, well-documented conventions, and company policies and procedures. An engineer may have earned a PhD in quantum physics, but that does not mean that he or she has ever taken the time to learn the proper way to punctuate a gerund phrase.

Each edit must be clearly communicated, and communicated with tact. Pose your comments as suggestions rather than directives, and be open to explanation. An author may have deviated from the standard, but he or she may have a very good reason for having done so. And always remember that the document is the author’s property. There may be times when you disagree regarding a particular point, but know when to pick your battles. If the author is dead-set against a change that you’ve suggested (whether or not he or she is correct), keep a record of the conflict and move on. Resist the tendency to engage in a power struggle, which may result in costly delays.

Keep in mind that a face-to-face conversation is a great way to take the edge off of a critique. Schedule a time to discuss your edits and to ask questions of the author. Build a relationship and show your own willingness to learn about the technical content of a document.

Consider creating an editorial review checklist. This is an efficient way to keep track of items (such as formatting and numbering conventions, capitalization standards, and rules for including acronyms) that may need to be assessed for each document. It’s also an appropriate place to document any specific disagreements that you may have with the author’s rejection of a suggested change. A checklist can serve as a tool for gathering metrics and tracking common mistakes and issues that regularly arise during the editorial review process. Finally, a checklist provides a means by which to secure your job as a technical editor; it will serve as the proof of your value to the company.

In these tough economic times, it may be difficult for a company to justify the added expense that an editorial review process may bring, but in the end, error-free deliverables will save the company effort and money. All documentation can use a little polish; as an editor, it’s your job to make it shine.

Obsessed with Possessives

Andrea Wenger

We see it everywhere: our schools, our places of business, even in notes stuck on our refrigerator. Yes, my friends, I’m talking about apostrophe abuse. The Obama administration, faced with two wars and an economy teetering on the edge of disaster, is unlikely to make this a priority. So it’s our duty as professional communicators to stamp it out.

My elementary school teacher made it sound easy. “To make a word a possessive, add an ’s, unless the word is a plural ending in s, and then, just add an apostrophe.” Ah, life was simpler in elementary school. True, many atrocities (such as Grammar Girl’s report of a menu advertising Ladie’s Night) could be avoided if people applied that straightforward rule. Yet there are myriad exceptions, and even the U.S. Supreme Court can’t agree on them (more on that later).

Pronouns

Possessive pronouns don’t use apostrophes: hers, his, its, ours, theirs, whose, yours. Most of us wouldn’t have a problem with this rule if it weren’t for the contractions it’s (it is, it has) and who’s (who is, who has). The sentence, Who’s book is this? doesn’t look wrong to me, but of course, it is. It should read, Whose book is this?

Personal possessive pronouns are often called absolute possessives, because they can occur with no noun following them. For example, a sentence could read It’s her book, or The book is hers. Absolute possessives are sometimes used mistakenly in conjunction with other possessives. For example, She worried about hers and his safety, should read, She worried about her and his safety. A better choice, though, would be to recast the sentence: She worried about her safety and his, or She worried about his safety, and her own.

Singular Words Ending in S

If a singular word ends in s, is it correct to add an s after the apostrophe in the possessive form? That depends on who you ask. It’s a matter of style, not grammar. As a technical writer, however, I consider it a usability issue. When people read, they hear the words in their head. So where the style guides disagree, I use pronunciation as the ultimate arbiter.

According to The Chicago Manual of Style, if an s at the end of a singular word is pronounced, the possessive is formed by adding ’s. The same is true for words ending in x or z: boss’s office, Alex’s wallet. However, if the ’s would be awkward, avoid the possessive and use of instead: the governor of Texas, the history of jazz. If the s, x, or z is not pronounced, the s after the apostrophe may be omitted: Illinois’ capital, Margaux’ necklace. Follow this practice only if you’re certain of the pronunciation.

Fowler’s Modern English Usage recommends omitting the s after the apostrophe with names ending in an iz sound, as in Beau Bridges’ brother.

The Associated Press Stylebook omits the s after the apostrophe altogether in singular words ending in s. Since newspapers are pressed for space, I suppose they can be forgiven (although I’m not sure I’ll be forgiven for that pun). But unless you’re required to follow AP, I recommend including the s for consistency with pronunciation.

Ancient Names

Ancient names can be troublesome, in part because style guides also disagree here. According to Fowler’s, ancient names ending in s form the possessive with an apostrophe alone: Achilles’ heel, Moses’ journey. However, according to Chicago, while names ending in an eez sound receive only an apostrophe, others use ’s: Aristophanes’ plays, Zeus’s wife. When in doubt, or when both ways look wrong, Chicago recommends using of, as in son of Isis or teachings of Jesus.

Multiple Possessors

Is it Joe and Renalda’s fishing poles, or Joe’s and Renalda’s fishing poles? That depends. Are the fishing poles joint property, or do Joe and Renalda each have their own pole? Placing an ’s only at the end of the group of names denotes joint ownership. Placing an ’s at the end of each individual name denotes individual ownership.

Attributive Forms

The distinction between an attributive form and a possessive is often unclear. A users’ manual isn’t a manual belonging to users; it’s a manual for users. Nevertheless, Chicago recommends retaining the apostrophe except in the case of proper names: citizens’ advocate, Panthers game, Boys and Girls Clubs of America.

Genitives

Analogous to possessives, genitives that denote value or time use an apostrophe, as in five dollars’ worth or two weeks’ notice. The apostrophe in this case stands in for the word of.

Double Possessives

In this idiom, also called a double genitive, a possessive noun or pronoun is used after of, to denote one example of several:
An associate of Sheila’s (or an associate of hers)
A collection of Bob’s (or a collection of his)

According to Garner’s Modern American Usage, some people dislike this idiom, but it has a long history and is widely approved. It can also be intrinsic to meaning: it wouldn’t make much sense to say a collection of Bob. Nevertheless, it might be better to recast the phrase as one of Bob’s collections.

Using an Apostrophe to Form a Plural

The practice of using an apostrophe to form the plural of abbreviations or numerals has fallen out of favor. The most common usage is to simply add an s: UFOs, the 1940s.

With lowercase letters, an apostrophe is needed for clarity. This is usually unnecessary with uppercase letters, but the apostrophe may be used where confusion might otherwise ensue, as in A’s, I’s, and U’s.

”Mind your p’s and q’s.
He got A’s and B’s on his report card.”
but…
He got Bs and Cs on his report card.

Chicago offers several examples of when to use the apostrophe to form a plural and when to leave it out:

maybe’s
ifs, ands, or buts
yesses and noes (or yes’s and no’s, especially if used with maybe’s)
dos and don’ts

For special cases like these, it’s best to consult a good style guide. But if you’re forced to rely on your own judgment, don’t obsess over it. When it comes to apostrophe use, intelligent people can disagree. Jonathan Starble(external link) wrote in Legal Times about a rift in the 2006 Supreme Court case Kansas v. Marsh: in the majority opinion, Justice Thomas consistently used Kansas’ statute, while in the minority opinion, Justice Souter used Kansas’s statute. Although I consider myself a political moderate, I have to side with Justice Souter on this one.

Reprinted with permission from the Carolina Communique(external link), the newsletter for the Carolina Chapter(external link).

Michelle Corbin Receives Distinguished SIG Service Award

Michelle Corbin Receives Distinguished SIG Service Award

The STC Technical Editing SIG is pleased to announce that Michelle Corbin, STC Associate Fellow, has received a Distinguished SIG Service Award(external link), or DSSA. Started in 2002, the DSSA is intended to recognize exemplary dedication to a SIG and its activities. The SIGs recommend qualified candidates, and the STC Board approves the recipients. The criteria for identifying nominees for the DSSA are length of SIG service, consistency of service over time, and variety of service.

Michelle Corbin

Michelle Corbin

Michelle served as the co-manager of the STC Technical Editing SIG for two years and as the immediate past co-manager for one year. In her tenure she helped revitalize the SIG and put procedures in place to keep it thriving. She has also served and continues to serve as managing editor for Corrigo, the STC Technical Editing SIG newsletter. She also wrote the strategic plan for the SIG and wrote a Tieline article about it. Her strategic plan can serve as a model for other STC communities to develop their plans.

Michelle will be honored at the annual conference along with other DSSA recipients. She will also receive a plaque in honor of her recognition. The citation on this plaque reads, “For your exceptional leadership as STC Technical Editing SIG manager and as newsletter managing editor and for your continuing selfless contributions to the SIG.” Please join us in recognizing Michelle Corbin for all of her past and continued contributions to the Technical Editing SIG.

Editing for the Next Generation of Readers

Jeffrey Japp

As I read Tony Self’s article “What If Readers Can’t Read” in the February 2009 issue of Intercom(external link), I began thinking about how editors should revise the way they edit textual content for the next generation of readers.

According to Self, “The speed at which information can be retrieved through tools such as Google is causing readers to become impatient. An Akami study in 2006 found that 75 percent of people would not go back to a website that took more than four seconds to load.” He continues by asserting that “our reading is moving toward skimming information horizontally, or reading snippets of text from different sources, rather than in-depth vertical reading.”

So how should we as editors respond to this trend? First, it is imperative that we shorten and streamline copy by removing all superfluous information. Too much text in a topic, whether it is in print or online, will increase the reader’s frustration at not being able to locate information quickly enough. Shortening text can be difficult because we deal with writers who may view every word as important and SMEs who feel that every possible bit of information should be covered in-depth. However, to ensure that we are communicating effectively to the target audience, we must be firm in our resolve to shorten and streamline copy.

The other area where we as editors can make an impact is in creating and editing indices. While this is less of an issue when a professional indexer is involved in the project, often budgetary constraints force writers to create their own indices which may not be as functional. On a recent document I edited, the index was little more than a copy of the Table of Contents. Because an index can help readers locate the precise location of the information they need, it is likely that there will be a shift from using a TOC to locate information to using an index. Self goes as far as suggesting that we abandon TOCs in electronic documents altogether.

If you are an editor who is not also tasked with writing, it may be prudent to get involved with writers early in the project. With an understanding of how documents should be structured to facilitate rapid location of information, we can assist writers in the development phase of a project by suggesting guidelines on how to design hierarchies of information. While this is less of an issue for organizations that employ structured documentation, it is invaluable for those still using more traditional documentation practices.

As content delivery changes, we as editors need to adapt the way we work to ensure that we assist in delivering content that is helpful and intuitive to our users.

Creating an Anthology on Editing

Avon J. Murphy

Pulling together New Perspectives on Technical Editing, an anthology on editing, was a complex, yet exhilarating experience. The process fell into four stages.

The longest stage was the gestation stage. I’d written an annotated bibliography on technical editing for the National Council of Teachers of English two decades earlier. Long a highly organized pack rat in careers as academic researcher, government research analyst, and finally editor, I had several hundred articles and a hundred books on technical editing. But something was missing from all this literature. As much as I’d gripe about the hole over the years, I couldn’t quite identify what I wanted. Tom Warren, of Oklahoma State University, challenged me to do something about it.

Energized by adrenalin, I charged into the second stage: What would we learn by looking at our discipline from different points of view at once? This question morphed into another: How much would we learn if recognized experts wrote separate chapters addressing the deeper questions suggested by their specific approaches to editing? Thus was born the idea of a collection of research-based and experience-based chapters looking at technical editing from various angles.

The collection eventually came to include such disparate angles—the “Perspectives” in the book title—as research methodologies, editing with electronic tools, editing within particular environments, the teaching of editing, and so on. Dozens of questions wrote themselves. For example, what methodologies can editing researchers best use? Is technical editing more complex than it was in the mid-20th century? What choices do teachers of technical editing have for designing their course? How can the structure of an organization dictate editorial career paths? How can copyeditors ensure quality? How have computers changed technical editing? What special problems do science editing and journal editing present?

The most challenging stage personally was getting the right people on board. As Technical Communication book review editor for nearly two decades and as manager of several research efforts, I’d been monitoring the careers of several accomplished editors; my short list of candidates was almost ready before I wrote it out. I was looking for original thinkers within their niches who had published a good deal, were dependable, and would keep me informed about their progress. Michelle Corbin, Angela Eaton, Barbara Gastel, Geoff Hart, George Hayhoe, Carolyn Rude, Tom Warren, and Jean Hollis Weber were all such people. The time-consuming part was to convince each individual to participate. I showed them the shape of the book, its contribution, the possible main points and resource leads, how the editors could individually contribute within their specialties, and the impact of this writing upon their careers. After some anxious weeks for me, all of them finally accepted the challenge.

The final stage was comparatively easy. Having lived so long with the book-to-be, I watched the proposal write itself. Baywood Publishing was the only company I seriously considered, and it quickly accepted the proposal. With schedule, style sheet, and chapter template on their computers, my contributors then set to work on what has become a most rewarding book.

As the writers submitted their chapters, my developmental editing focused on innovative thinking about questions, acceptable research methodologies, avoidance of excessive duplication among chapters, and incorporation of already published literature. On the second and third drafts, I focused more on voice, paragraph structure, sentence clarity, and formatting within my template restrictions.

The full manuscript went to Baywood in late September 2008, Baywood approved it in mid-November, and I sent the slightly revised files in early December. The manuscript is now (late April 2009) in typesetting. After proofing, correcting, and indexing, the book should appear in something like 15 weeks. I’m certainly happy to be working with a publishing firm that stresses the importance of high-quality procedures, including editing. Would I want to edit another anthology? Ask me after I’ve recovered from this one!