Introduction
In Part 1, I presented background information about my research on editing Wikipedia articles.
Continue reading “The Future of Editing in Web 2.0: Wikipedia and the Role of the Editor (Part 2)”
In Part 1, I presented background information about my research on editing Wikipedia articles.
Continue reading “The Future of Editing in Web 2.0: Wikipedia and the Role of the Editor (Part 2)”
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.
In the engaging chat, Andrea gave three important strategies to simplify the writing style.
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
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
Janice Gelb
In 1994, Sun Microsystems PubsBook, a fluorescent-colored two-binder set of internal publication guides, won the International STC Conference Technical Publications Best in Show award. The set included our comprehensive editorial style guide, which was first released internally in 1990. A lot of people at the international conference wanted to know whether they could get a copy of the style guide, but we explained that because it contained proprietary information, we couldn’t distribute copies.
After several requests to this effect, we had a Judy Garland/Mickey Rooney moment: “My dad has a barn and your mom has a sewing machine so let’s put on a show!” Only in this case, it was more like “We have a comprehensive editorial style guide for technical publications and, based on all this demand, no such neutral guide exists commercially so let’s publish one!”
We had already developed a process for managing updates to the style guide. The original style decisions were made by our corporate-wide Editorial Forum, although later editions were shepherded by a smaller team. Team members discussed and voted on proposed changes, and occasionally subteams were created to develop proposals for structure and wording. Proposals for more global or more contentious changes were brought back to the entire Editorial Forum for discussion.
Given this experience, we originally thought that turning our internal style guide into a commercially neutral one would be fairly simple. However, we were quickly proven wrong. Our first step was to have each chapter owner identify and remove all of the potentially proprietary information. Next, because we wanted the style guide to be universally applicable, we tried to identify style guidelines that were prescriptive for our writers but that are a matter of preference rather than grammar (such as serial commas). For those guidelines, we included information about why we recommend a certain decision but changed the wording so that it didn’t require adherence to one style or the other.
Finally, we decided to add PC and Macintosh examples rather than using all UNIX examples. An unexpected difficulty was inventing a company name for the examples that wasn’t already being used by a real company! After much web searching of computer puns and nonsense names, I finally came up with “Plirg.”
The only new material that was added to the commercial version of the style guide that was not in our in-house version was an appendix providing some general information about how to promote and develop a publications department, which obviously wasn’t needed in our internal guide. This appendix was the only large piece of original writing in the guide, and was my most time-consuming assignment for the project.
Towards the end of the external style guide project, two editors did a final proofreading. I incorporated their comments and did a final index pass, reconciling existing entries and adding new ones.
As the project lead, I was the liaison with the publisher (Prentice-Hall PTR, now Pearson Education). We had a few thorny problems with production, the first of which was that Prentice-Hall used different FrameMaker templates for their books than the internal ones we used for our style guide, and a smaller page size.
Another problem was the desire to include with the first edition a version of our corporate electronic FrameMaker document templates, and a version of the book that could be read by FrameViewer. (Remember when FrameMaker was the universal technical publications standard software?) Even after the book’s publication, the electronic FrameViewer version caused technical problems. Also, I had to reject not one, not two, but three supposedly final “gold” masters (“Ready to send to the printer as soon as you say OK”) due to various problems, including one set that contained two Chapter 2s!
One of our most difficult decisions was what to name the book. I can’t tell you exactly how many puns were submitted on the word “write” but there were many. We finally settled on Read Me First. Because Prentice-Hall had already published a book about SGML whose title began with “Read Me First,” they requested that we either add an exclamation point and a subtitle or change the title to Read This First. We chose to go with the subtitle.
The first edition of Read Me First! A Style Guide for the Computer Industry was released in early 1997. The third and latest edition is available online now for Safari Online Books members and will be available in print in early November 2009. This latest edition includes guidelines for writing alternative text for accessibility, using wikis for documentation, and creating screencasts.
If you’d like to read more about developing corporate style guides, see Developing a Corporate Style Guide, one of the Best Practices series of booklets by Sun Microsystems, available at Vervanté.com or Amazon.com.
Janice Gelb is a Senior Developmental Editor at Sun Microsystems.
Editor’s Note: This article is an interview with John Kohl, the author of The Global English Style Guide: Writing Clear, Translatable Documentation for a Global Market. John has been working at SAS Institute as a technical writer, technical editor, and linguistic engineer since 1992. His book is available from SAS Press and from many online booksellers. John will be presenting on this topic at the October 2008 membership meeting of the Technical Editing SIG, and we wanted to whet your appetite with this interview for attending our meeting!
What central problem does your book, The Global English Style Guide, address?
The need to communicate clearly to a global audience—an audience that includes non-native speakers of English, translators, and perhaps also machine-translation software, as well as native speakers. The Global English guidelines are based on empirical research, and the book provides much more detailed explanations of these guidelines than can be found in any other single source.
What was your motivation for writing your book?
I’ve studied foreign languages (German, French, Russian, and Spanish) and have taught English to non-native speakers. As a result, I have a lot of empathy and understanding for people who are reading in what, for them, is a foreign or second language. I understand how much of a difference the style and vocabulary in a document can make to a non-native speaker’s ability to comprehend the material.
I’m also very sensitive to the types of ambiguities that leave translators scratching their heads. Translation is more efficient and more accurate when the English source texts are written clearly and simply.
What made you decide to publish these guidelines?
I really did not want to put the time and effort into writing this book, so for 15 years I waited, thinking that surely someone else would write it (or a book like it). In the meantime, I was speaking about Global English at various conferences and offering workshops at SAS and for a few other companies. I could see that there was a lot of interest in the topic and a need for an example-driven book that covered the topic thoroughly.
When I finally decided that I should write the book, I was pleasantly surprised that SAS Press was interested in publishing it. It’s the first book they have published that does not pertain specifically to SAS software or to software-related topics. The opportunity to work with them instead of with an outside publisher made the prospect of writing and publishing the book less daunting. I don’t know if I’d have written it if I had had to seek an outside publisher.
What features of the book especially pleased you?
I’m happy that I was able to cover the topic as thoroughly as I did. Some authors on the topic of writing for international audiences have done little more than admonish authors to “write clearly.” That advice is not very helpful! Writers and editors need specific guidelines that help them recognize ambiguities and other unnecessary impediments to the translation process. And they need enough of an explanation and enough examples that they can actually understand and apply those guidelines. I’ve done my best to meet those requirements in this book.
What is your most significant finding?
I think my most substantial contribution has been my research on syntactic cues—the little function words (usually “closed class” words such as pronouns, prepositions, auxiliary verbs, and so on) that many writers and editors have been taught to eliminate, but which are often essential for eliminating ambiguities and for improving readability. I’ve done a very thorough job of identifying and explaining the contexts in which these syntactic cues add clarity and improve translatability.
Doesn’t the use of syntactic cues increase the word count, leading to increased translation costs?
Not necessarily. In my book, I emphasize that authors and editors should think about content reduction at the same time that they are applying the Global English guidelines. In my own writing and editing, I find that I eliminate at least as many words as I insert, even when I am focusing only on sentences and paragraphs and not looking for entire topics that could be eliminated. So in the end, there is an overall decrease in localizable content.
Even if that were not the case, clarity and disambiguation are essential for producing quality translation. If you sacrifice clarity by eliminating syntactic cues, you might increase localization costs by forcing translators to seek clarification on unclear phrases and terminology. In addition, your risk of having incorrectly translated information in your deliverables increases, with potentially disastrous and expensive consequences.
What role does language technology play in this process?
As I was writing the book, acrocheck™ software was an invaluable research tool for collecting and analyzing examples of linguistic patterns. We are also using acrocheck at SAS to help our writers and editors follow our terminology guidelines and style guidelines, including many of the Global English guidelines. I’m an absolute believer that this type of technology should be used more widely. No writer or editor can keep extensive style guidelines and preferred terminology lists in mind while working on a document. Software such as acrocheck is far more efficient for this. Our writers and editors follow our guidelines much more consistently than they could if they had to look up rules or terminology lists online or on paper.
What kind of metrics have you used to quantify the benefits of using language technology or of following the Global English guidelines?
We have not found a need to try to measure the benefits of using acrocheck or of following the Global English guidelines. For anyone who uses this type of language technology and who reads the guidelines and examples in my book, the benefits are intuitively obvious. Everyone in our Documentation Division recognizes the importance of our guidelines, and our writers and editors are happy to have a tool that helps them follow those guidelines.
The documentation process is more efficient because writers fix many of the errors in their documents before turning those documents over to editors. Editors can focus more on content reduction and on other issues that decrease costs and that add greater value to our documentation.
Your book includes 49 major style guidelines, plus dozens of other guidelines for punctuation, capitalization, and terminology. If you had to narrow those down to only ONE, what would be the most important guideline you’d like to see companies use in their authoring?
The in-house translators at SAS once told me that “Limit the length of sentences” was the most important guideline. That guideline is certainly important, but not all long sentences are difficult to translate. So, personally, my favorite guideline is “Make each sentence syntactically and semantically complete.” The book contains several more-specific guidelines about how to do that, but here is one example:
In order to translate the first version of the sentence, a translator has to read between the lines and has to have a very good understanding of the context and subject matter. The translator essentially has to rewrite the sentence as I did in the revised version, supplying the missing content, in order to translate it. Translators should not have to compensate for authors who don’t express their ideas completely!
Thanks, John!
Ben Davies
For the past year, I’ve been a technical writer for an engineering-based company. As a result, I often deal with difficult-to-understand documents written by technical people. Without reading these documents, an outsider might assume they are complicated because they are filled with complex information; in reality, the documents are complicated because of the way they are written.
The following paragraph is an example of a paragraph that is very complicated because of the way it was written:
After reading this paragraph, the following question comes to mind: Is using radio buttons so complicated that you actually need to provide a detailed example?
I call such paragraphs “passion fluff”—text that someone has put a lot of time and effort into writing but that really say nothing.
The “fluff” in the example above is all the times the author re-iterates the same concept in different ways in an attempt to clarify an already convoluted set of instructions. The example itself is “fluff”, because using radio buttons isn’t complicated.
I decided to re-write this paragraph to see if I could take out the passion fluff and came up with the following:
I had an epiphany last year when I realized people don’t like to read, especially when they are trying to complete a task. Therefore, essential information buried in long, convoluted paragraphs is useless. Most technical writers already know this, and I hope I’m preaching to the choir; however, many subject matter experts don’t know this, especially if they came from University where writing long (10+ lines), convoluted, academic-style paragraphs and sentences (like this one) are a way of life.
Contrary to popular belief, academic writing has no place in the business and technical world of documentation. Because of this, it is our job to teach passion fluff writers what is acceptable and what isn’t. Allowing someone to get away with passion fluff does two things: it lowers your expectations of the other person’s writing ability, and it encourages the other person to continue writing incorrectly.
Remember, though, that passion fluff is very difficult to deal with because of the passion that’s involved.
A strategy you could take to help passion fluff writers is to re-write something they’ve written to show the value of clear communication.
The goal of re-writing something isn’t to prove how badly they write, but to make them better writers. Show them what is right, rather than showing them how what they did was wrong.
Reprinted from Manuscript, the newsletter of the Manitoba chapter of STC, by permission of author and editor.