Monthly Archives: October 2008

Welcome to My World

Don W. Benesh


My writing career developed from many years of writing training material (instructor guides, training schedules, handouts, etc.) after not being provided what I considered adequate material while working as a trainer. In addition to being a trainer, I spent some time as project manager, where I also wrote my own operating procedures, project plans, proposals, and business plans—for the same reason. By doing all this writing, I developed better than average skills as a writer, but only in support of my primary fields of interest—or so I thought.

During an interview about 10 years ago, the conversation migrated to training; when asked about the material I used, I mentioned I wrote my own—and I happened to have samples with me. The interviewer was more interested and impressed with my writing skills than my project management background. She suggested I look into technical writing opportunities and said she would be doing me a disservice hiring me as a project manager when I write “better than candidates coming into the office claiming to be a technical writer.” I thanked her, but had no idea what a technical writer was and didn’t want to appear uninformed by asking.

I searched “technical writing” on a few of the Internet job boards and discovered endless opportunities, but still had no idea what distinguished technical writing skills from all the writing I had done over the years. So I took a commercial technical writing course (about 150 hours) and became a Certified Technical Writer.

The course focused on technical writing best practices. By the end of the training, students developed a portfolio of help files, hardware and software user guides, and some Web development work. For me, the course wrapped up what I had been doing over the years into a neat package and a new career. WOW—I do that!

What I took away from the class was “best practices” for the work I had done previously, including parallel construction, consistency, and readability (not to mention the certificate and new portfolio). I was immediately hired as a trainer for a new company because I was also “a certified technical writer.” I had almost two years at that company as a senior trainer before the collapse of the dot-com boom forced layoffs.

New Career

With this background and experience I secured a new job where I was initially hired as a technical writer where I anticipated doing what might typically be expected of a technical writer—work with SMEs and write hardware, software, and network technical documents.

I was introduced around the office as the new technical writer (I discovered I was the only technical writer) and then given a completed manual. I was sent an e-mail with the soft copy of the manual and instructions to “sort of clean it up and fix anything that isn’t appropriate from a technical writer’s point of view.” When inquiring about a style guide, I was told (with a slight grin and chuckle), “that’s part of our problem, we don’t have one.” At the end of the first week, I had spent just over 30 hours on a manual of about 35 pages and figured that was all I could do. But my boss was extremely happy with the results. (Isn’t that all we really need to do … keep the boss happy?)

At the beginning of my second week I was given a stack (about 40 or so) of already written manuals and told to “clean them up.” Whoa, that’s a year’s worth of work! (Remember, I had just spent about 30 hours on one manual.) And “by the way, they are due in three weeks.” After about 200 hours they still needed work, but they were better. (Anyway, they were in on time—that was a hellish three weeks!)

By the third month I had more than 150 manuals cross my desk and accepted the fact that I would not be writing manuals, but editing—sometimes very substantially, when I had the time.

Over the next few months the company’s reputation for quality manuals grew—the client was most impressed—and senior management began to realize the need for the service I provided.

Building a Technical Publications Department

I believe my success as an editor was due to several factors: I was the only technical writer (nothing to discuss—what I said went); as a past project manager I was used to making decisions on the fly and moving on; and I started a technical writer’s tips bulletin.

From the manuals on my desk, I compiled a list of names (engineers/authors) and created a distribution list for my almost daily tips. Each tip addressed one topic with examples of what I have seen (incorrect) and what I want to see (correct). I also quoted sources—typically The Chicago Manual of Style, but also other references focused on technical writing, anything I could find to support what I wanted to see.

To encourage people to read these bulletins, I offered lunch to anyone who could find an error within the bulletin and regularly left an error to be discovered. I also have an odd sense of humor that I injected into the tips; such as, “Any questions? Yes, you in the back row … very good question!” then proceeding to provide an answer to my imaginary question. Judging by the comments I received, those on my distribution list enjoyed getting my tips and actually read them—and the manuals coming to my desk started improving.

After comments started coming back from our client about the improvement of our manuals, senior management began to take notice. I was asked what else could be done to improve the manuals. I suggested hiring a few more technical writers or sending all the authors to a technical writing course, or at least a workshop introducing them to technical writing best practices. A few days later I was asked if I could arrange such a workshop.

I contacted my technical writing mentor, who no longer taught the 20-week course but did provide on-site workshops—both a 1-day and 2-day outline. We contracted for a 2-day session and a few months later a 1-day session; we had about 12–16 people attend each workshop.

After the first year my boss was extremely impressed with my results, expressed with the comment: “Look at all you’ve done and you did it without stepping on any toes, or ticking anyone off. You are really well liked.”

Technical writers became an essential part of the project team. When the company secured two new projects, I was involved in hiring technical writers for the new projects. Later I recruited two temps for the project I was on; one was released after the 6-week contract, while the other was kept on permanently.

The first year I had one manager who pretty much left me to do what I knew needed to be done. After his promotion, I and the document controller (an administrative position responsible for distribution of all incoming and outgoing correspondence) were passed around to no fewer than six managers over the next 12–15 months. Finally, my last manager, upon leaving, recommended I take over the team I had pretty much created and virtually led—by this time, three technical writers and the document controller. The new project manager agreed and a new cost center was created—Technical Publications.

I stressed that documentation that goes to our client should get the same consideration as a four-color glossy sales brochure. I preached that there are two aspects to document quality: technical accuracy and literary presentation. While the engineers are responsible for technical accuracy, the technical publications team is responsible for literary presentation. Technical writers must keep in mind that our finished product is more than just a software or hardware specification; it represents and reflects the quality of the specifications.

After two years I finally had the time to actually write a manual (well, I was hired as a technical writer, wasn’t I?) and the original tech tip bulletins (about 75 tips) were compiled and became our style guide.

For almost six years, I have focused on setting a higher standard for our client documentation and the company in general. The first group of 40 manuals crossed my desk about 4 times, each time getting a little better. Comments from outside the office went from “great product, but lousy documentation” to “very impressive manuals…better than the other contractor” (an actual quote from one of our clients.)

Although I started out as a trainer and project manager, now I consider myself a technical writer/editor.

Thoughts on Copyediting, Outsourcing, and the Technical Communication Profession

Russell Willerton

In July 2008, Business Week published an article by Nandini Lakshman called “Copyediting? Ship the Work Out to India(external link).” This article focuses on Mindworks Global Media, an Indian company that handles copyediting, layout, and reporting tasks for several American newspapers.

When Mindworks started, the company took on Indian clients. Over the past several years, however, the company has taken on more U.S. clients as readership of print publications has declined and cost-cutting efforts have increased.

Nandini writes that outsourcing work to India helps keep publications in business. She quotes Mindworks CEO Tony Joseph, who said editorial outsourcing “helps [publishers] improve efficiencies in editorial packaging and reallocate resources to reporting and writing.” Mindworks told Nandini that the company helps publications cut costs 35% to 40%.

I posted a query to STCTESIG-L on July 11—primarily out of curiosity—to ask if anyone was familiar with copyediting of technical publications being outsourced to India. (Clearly, such a question reflects the fact that I live and work in the U.S.) Virginia Janzig, Ben Jimenez, and Marie Highby cited examples of copyediting being done by or in tandem with employees in India. Gururaj B. S. and Sankara Rajanala pointed out that while many editors work for Indian companies, work done by Indian companies is not always outsourced work.

We know that native speakers of a language often reach a level of fluency in that language that can be difficult for others to achieve. Said Jennifer Collister, working in the U.S. for a company founded by Indians, “When I’m editing pieces of the proposals, I can tell just by the writing style who is a native English speaker and who isn’t. However, the non-native English speakers get their point across but are just making grammatical and sentence structure mistakes.”

I suspect that this not-quite-native fluency in English contributes to a reduced level of confidence many U.S.-based writers might have in work done by editors whose native language is not English. Janice Gelb’s comments reflect such sentiments: “The cost of hiring an inexperienced or less competent employee (and I hasten to add that I am not speaking specifically of employees in India) often appears to be less in strict monetary output but in fact does cost the employer in the long run. These costs are both in real dollars (cost of redoing unacceptable material, increased cost of translation, increased volume of support calls, and so on) and intangibles such as customer product satisfaction and perception of corporate concern with quality.”

However, a detailed post from Sankara Rajanala (affirmed on the list by Mike Boyd), provided a different view. I provide these excerpts.

“It is not true that non-native speakers can never do as well as native speakers, especially when it comes to writing and editing. Eminent examples of this are Joseph Conrad and Vladmir Nabakov. I am deliberately omitting Indian authors…. Recently, I was on a conference call with a lot of new ‘faces’ (new to me). The next day I was asking a friend who was also on the call (from a different location) who the American on the call was; he said everyone is an Indian: turns out, one was based in the U.S. for a long while and I mistook him for an American…. No one can defend outright ungrammatical use of English but there are a lot of Indianisms that make our use of English colorful (to be avoided in technical documents for sure) and the name of the game is accommodation….
Not so long ago American English itself was dubbed as Americanisms, until H. L. Mencken got into the act. Right now, there are many Indians who proudly say ‘we are like this only’. But on the job, we diligently follow the norms of whichever language (Am, Brit) we are supposed to be writing in.”

Don Cunningham, professor emeritus at Auburn University, wrote that recent trends in outsourcing reflect on the state of the technical communication as a whole. “If we do not market ourselves and our profession effectively we will likely lose a significant amount of work to those who are willing to work for less. And this is not totally a geographical/locational issue.”

Adrienne Maxie pointed out that jobs do not necessarily belong in any one country. She asks, “What if we changed the way we looked at ‘our jobs’? Technically, the jobs don’t belong to ‘us’; rather they belong to the employer who then contracts with us to provide a specific task in exchange for a monetary value. Since the jobs do not belong to us as writers, editors, etc., then the employer can contract with whomever he or she decides can provide the most output for the least amount of money.”

Ram Venkatraman’s comments (in excerpts here) reflect a similar view:

“The other day, while holidaying in a remote Indian town, I met three young Frenchmen. Two of them had just completed their engineering degrees and secured internship in an Indian company. The third young man is expecting to complete his degree in networking technologies sometime next year and took my business card and promised to get in touch with me when he is ready to take up an internship. This is what students in India did when they did not have opportunity in their homeland decades ago. That is what I did….Now, while I totally understand the concerns of folks whose jobs might migrate to other countries where cheaper labor is available, the big picture is a historical transformation that has been shaping up for centuries. Like the three Frenchmen, people may move to places where there are opportunities. Living and earning in India can provide the same lifestyle as earning and living in Germany. Millions of people around the globe do precisely do that. My family moved to study in US more than a decade ago. Then, one fine day we moved back to India because the opportunity was there. If the opportunity moves to Timbuktu, I will be packing the bags again.”

This discussion reminded me that technical communication is one of the many facets of the global economy, and that technical communication tasks can be done from any spot on the globe. Wherever we find ourselves, we must demonstrate and articulate the value we bring to our employers and their consumers. Standing still will ensure we get left behind.

Scholarship Winner’s Passion for Technical Communication

Michelle M. Schoenecker

Editor’s Note: This year, the STC Technical Editing SIG offered scholarships to one undergraduate and one graduate student in technical communication. One part of the scholarship application was to describe a project or research that the applicant was involved in. We asked the scholarship winners to write a newsletter article summarizing their project or research. This is the first of such articles from our graduate scholarship winner.

At the risk of sounding really clichéd, technical writing is truly my passion. I began my career in 1999 when I took a proposal management position at a large banking automation company. I discovered that I had a talent for technical writing and editing and I wanted to focus my career in this area. Thus, I joined STC and the Technical Editing SIG, and enrolled part-time in the Master’s program in Professional Writing at University of Wisconsin Milwaukee (UWM) in 2004. In 2006, I became a technical grant writer in the College of Engineering at UWM writing research proposals and editing journal manuscripts.

To integrate my professional experience with my education, I accepted a position as a student researcher and editor for Dr. Gerald Alred, Professor of English at UWM, to help develop the 2009 editions of his technical writing reference books, The Handbook of Technical Writing and The Business Writer’s Handbook. I eagerly accepted this position, knowing it was a rare opportunity to work closely with one of the most influential technical communication scholars on two widely used and highly regarded texts. Through this experience I gained valuable technical editing experience, applied the knowledge I gained from my graduate education, and glimpsed into the world of textbook publishing.

While the impact of the handbooks on the technical communication field is significant, it is their impact on future technical writers that is most important to me. As a result of working on the handbooks, I feel a greater responsibility to share the knowledge I have gained throughout my career and education with the technical writers who will follow me. I want to become a role model for future technical writers and help them prepare for the expectations and demands of workplace, as well as enlighten them with the excitement, challenges, and satisfaction that careers in technical communication can deliver.

As I look ahead to the next phases in my career, I intend to keep working as a professional technical writer so that I can integrate my knowledge and experience into my teaching. I believe that if future technical writers are to succeed in the rapidly changing workplace, they must have practical experience and flexible skills to meet the demands of our profession. It is an exciting time for the technical writing field, and my goals are to continue promoting excellence within the field by demonstrating the value we bring to those who employ us, and to prepare successfully the next generation of technical writers who will follow us.

I am sincerely grateful for the STC Technical Editing SIG scholarship – it is truly an honor to be a recipient and I look forward to completing my graduate studies.

Getting the Source Text Right with John Kohl’s Global English Style Guide

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(external link) 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!

Source text

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:

Not Global English:
Space is tracked and reused according to the REUSE value when the file was created, not when you add and delete records.
Global English:
Space is tracked and reused according to the REUSE value that was in effect when the file was created, not according to the REUSE value that is in effect when you add and delete records.

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!