Author: Yoel Strimling

Posted on

The Making of a Commercial Style Guide

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(external link) or Amazon.com(external link).

Janice Gelb is a Senior Developmental Editor at Sun Microsystems.

Posted on

Let’s Change the Career Paths for Technical Editors

Jean Hollis Weber

Traditionally, trainee editors were expected to become good at copyediting before an employer would allow them to do substantive (or developmental) editing, and senior editors were expected to work well at both levels. In my view, this is a short-sighted and outdated approach to a career path, especially for instructional and technical writing. It does a disservice to both editors and their employers.
The skill sets for copyeditors and substantive editors are different (a focus on details versus the bigger picture; rules versus analysis; strong English-grammar skills versus strong analytical and problem-solving skills). Both skill sets are important, necessary, and valuable; but good substantive editors may be poor copyeditors and vice-versa, although some people are good at both.

I’ve worked with people who had superb analytical skills (finding problems in the text or inconsistencies between the text and the product being documented, and often suggesting very good solutions to those problems) but who had only a basic understanding of some punctuation and grammatical issues. As long as these people were tasked only with substantive or usability editing work, they were extremely valuable on the project, because they tended to spot problems that the subject-matter experts did not notice: errors in logic and structure, unstated assumptions, use of idiom and colloquialisms, and other problems that native speakers miss. Teamed with a skilled copyeditor, such a substantive editor can be a major asset to an organization.

Today’s technical editing environment has expanded to include usability editing, mainly of electronic documents (Web pages, wikis, PDFs) but also printed instructional material such as user guides and repair manuals. Usability editing is concerned with the suitability of a document to meet its readers’ needs in terms of organization, presentation, navigation, and other factors. We all know that grammatically correct text is of little use if the instructions are unclear, steps are out of sequence or missing, or if the audience can’t find the information required. Usability is an area in which analytical and problem-solving skills—and people skills—are more valuable than grammar skills.

The best copyeditors go beyond the basics when editing. They find inconsistencies (“Figure 6 shows the back of the machine, but the text talks about the buttons on the front”), check facts (“the Apple Inc. logo has not been rainbow-striped for many years, and the company name has changed from Apple Computer Inc.”), and point out audience-specific issues (“your audience is international; most of them think 12/4/2010 means April 12, and many of them think ‘summer’ is December through February”). They have read widely, so they spot typos like “For Whom the Bells Toll” and a ZIP code starting with 2 for Spokane, WA, and they know that Stephen Hawking is British.

My career has included scientific editing, technical editing (copyediting, substantive editing, and usability editing), technical writing, and documentation project planning and coordination. I am well aware that I am better at dealing with the “big picture” than I am with the details, and I am much happier and more productive as a substantive or usability editor than as a copyeditor.

In my experience, most editors work best at either the detail level or the “big picture” level, and indeed prefer one or the other. Others have reported the same experience. For example, in June 2003, during a discussion on the STC Technical Editing SIG mailing list about the development or “maturation” of a technical editor, someone commented,

“During the last three years, we outsourced the editing… Some [editors] were more experienced with doing substantive editing and some with copyediting…

“We found that the two editors who could perform substantive edits at the macro level both needed intense instructions and deliberate coaching when assigning them copyedits. Otherwise, they would ‘go overboard’ and perform a more substantive edit every time, which was very unnecessary and didn’t match the client’s defined processes. BTW, these editors were highly technical and for our client, could very easily understand the jargon and products, which made them expert at seeing gaps in the writers’ instructions and conceptual text.

“Conversely, the copyeditors had great difficulty ‘stretching’ to do more substantive edits.”

My conclusion? We should change the career path for technical editors from a progression (copyeditor to substantive editor to senior editor) to some arrangement that allows all editors to be recognized, promoted, and financially rewarded for improvements in skills and productivity in whatever they do. This arrangement could involve having at least two progressions or tracks (one for copyeditors and another for substantive editors), but that might put impediments in the way of people who want to “change tracks.” A workable and equitable system would benefit both editors and the companies who employ them, so let’s start now to develop one.

Jean has a chapter titled “Copyediting and Beyond” in New Perspectives on Technical Editing, ed. Avon Murphy, Baywood Books, [In Press, due 2010]. She maintains a web site for technical editors, http://jeanweber.com/(external link).

Posted on

Election results for your 2010 TE SIG officers

Meredith Kinder and Vanessa Wilburn

The votes are in!

Congratulations to the STC Technical Editing SIG officers for 2010!

  • Jeffrey Japp, 2010 – 2011 Co-Manager
    (Vanessa Wilburn will continue in 2010 as second term co-manager)
  • Charles Crawley, Treasurer
  • Lori Meyer, Secretary
  • Donna McManus, Membership Manager

In addition to these elected offices, we also have a great team of support volunteers working to make the SIG a success.

Thank you to everyone who has committed to take a lead role next year.

Posted on

The Technical Stylist Meets the Definite Article: What Bloody Man Is That?

Kathy Underwood

In Act I, Scene 2, of Macbeth, a blood-soaked sergeant enters the presence of King Duncan, which prompts the king to ask the obvious question:

“What bloody man is that? He can report,
As seemeth by his plight, of the revolt
The newest state.”

What is the answer to this kingly question? That’s a usage pundit reporting some change in language usage that seems likely to provoke controversy. And that’s me after one of those interminable style discussions that characterize editors’ meetings. I sometimes—well, often—feel that I’ve just left the battlefield and that I need to find the nearest medic. It’s not that we’re all contentious. (In fact, very often these discussions are more like rowdy, amusing party games.) It’s just that the topics we address are fraught with complexities that make the plot of the Scottish play look like Dick and Jane. Worse yet, we frequently struggle with questions that few if any customers would ever recognize as questions.

Take the definite article. Please. The editors at SAS continue to struggle with the question of which SAS product names require the definite article and which require the zero article (linguist-speak for no article at all).

How do you make such a decision in the absence of clear guidelines from the usual usage manuals that we consult (Chicago Manual of Style, Harper’s Dictionary of Modern American Usage, etc.)? In the interest of precision, we have to make choices not unlike those parodied in the show Beyond the Fringe(external link) in the 1960s. In a sketch entitled “Portrait from Memory,” Jonathan Miller as Bertrand Russell meets the philosopher G.E. Moore, who, as it happens, is holding a basket of apples on his knees. Russell asks Moore if there are any apples in a basket. Moore says no. Then Russell asks if there are some apples in the basket. Moore says no. Finally, Russell asks Moore if he has apples in the basket. “’Yes,’ he replied. And from that day forth we remained the very closest of friends.” (Can you imagine what Moore would have been like in editors’ meetings?)

For our in-house style guide, my worthy colleague and fellow editor, Joel Byrd, created an article on the use of the definite article with product names. He reified our department’s lengthy and ongoing collaborative discussions and e-mails and produced a very useful table as well as a field test to help us make the best choice. Here is my paraphrased version of the guidelines:

  • Use the definite article if the primary noun is countable (example: “the SAS Forecast Server”).
  • Use the definite article if there is general industry agreement that the primary noun requires a definite article (example: “the SAS Intelligence Platform”).
  • Use the zero article if the primary noun is uncountable (example: “SAS Business Intelligence”).
  • Use the zero article if the primary noun is a metaphor “that does not have a defined, commonly accepted meaning in the software industry” (example: “SAS Management Console”).

The test devised to assist the editor is as follows:

  • Write the primary noun in lowercase and then in uppercase (for example, “console” versus “Console” and “the console” versus “the Console”).
  • Does the name of the object in isolation mean the same thing as it means in the product name? If so, use the.

Based on several examples of SAS product and component names, I decided to create a list of our extant primary nouns so that we could have an at-a-glance guide for new product names and whether or not they should take the definite article.

  • Use the definite article with these primary nouns:
    • platform
    • portal
    • provider
    • server
    • software
  • Use the zero article with these primary nouns:
    • analytics
    • console
    • intelligence
    • studio

This list should be satisfyingly clear. But consider the problem with console. Our basic rules say that if the primary noun is uncountable, we should use the zero article. But the word console is obviously countable. On the other hand, in the land of product names and software products, console is a metaphor and not countable. Very crazy-making. So every time I come across a product name with the word console in it, my editing hand wants to insert the definite article.

There’s an even bigger problem. With any usage guideline, there’s a “missing middle” (one or more ungrounded assumptions) in the syllogism. That is, when and how do we decide that a given agreement has reached a critical point that forces us to change our guidelines? Yes, you guessed it: We have to have another editors’ meeting.

Why is it that grammar and usage rules, which once mastered should provide comfort and confidence, can be so frustrating? Why are there so many exceptions to cope with? And why do all those usage pundits have so many different opinions and remarkably little consensus? I think that those questions are answered succinctly by Otto Jespersen in his introduction to The Philosophy of Grammar (found in the first sentence of Chapter 1):

“The essence of language is human activity—activity on the part of one individual to make himself understood by another, and activity on the part of that other to understand what was in the mind of the first.”

Even if we think of the effects on language of just a few of the more dramatic forms of human activity—revolutions, inventions, and catastrophes—we quickly realize that language is a quivering, changeful thing. From vowel shifts, to spelling, to syntax, language always reflects the psyche of any given group. (And which psyche is more shifting than that in the software industry? A new product or technology can completely change perspective.) That’s especially true when society is in flux. It’s that shared, shifting psyche that dictates what really happens with language. And we might argue that the shifting is where the sublime arises.

As editors, we often have to make many decisions that we know will ultimately prove ill-advised, if not completely wrong, and that any number of our fellow editors will find objectionable. But that’s what human activity, war, peace, and the dialogue of the psyche are all about.

Think of the changes from “on line” to “on-line” to “online” that have occurred over the past few decades. There was no legislation, there was no vote, and there was no universal epiphany. So why did “on line” and “on-line” drop out of use (mostly—they are still used in some settings)? In The Fight for English, the linguistic historian David Crystal says that the short answer to questions about disdained usage is “somebody thought it was wrong.” (See Crystal, page 110. Crystal’s book, by the way, is a very readable history of grammar practice and grammarians over the past few hundred years.)

All editors, and especially those of us who serve on in-house style teams, have to make arbitrary decisions all the time. We must be as autocratic as is essential to produce a cohesive body of documentation. But we can never lose sight of the world outside our doors. We have to listen to that bleeding sergeant even if we don’t want to or haven’t got the time to hear what he has to say.

Posted on

Scholarship Winner: Internships Stretching One’s Abilities as a Communicator

Daniel Seipert

Editor’s Note: Once again 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.

I first discovered my interest in technical editing while an undergraduate at the University of North Carolina at Charlotte, where I earned an internship with the Environmental Assistance Office on campus. As an intern I edited several laboratory reports on soil composition and water quality, some of which provided the extra challenge of editing for authors who were non-native English speakers. I enjoyed this work so much that I decided to pursue my Master’s in technical communication at East Carolina University (ECU). My graduate assistantships at ECU gave me many opportunities to work as an editorial assistant on projects for IEEE Transactions on Professional Communication and the program committee for the 2008 Conference of the Council for Programs on Technical and Scientific Communication. I have also been able to work with the Renaissance Computing Institute at ECU, designing their website, newsletters, and brochures.

Perhaps my most challenging and fulfilling project, however, was a comprehensive edit of 12 chapters for an academic book on the global digital divide. One of the project’s most valuable qualities for me was the opportunity to again edit for English as a Second Language (ESL) authors. On the surface, this process required me to address syntactic and lexical issues common among ESL authors, such as misplaced prepositions, incorrect articles, and non-parallel structures. But, I also had to be aware of any underlying cultural considerations that may have led to these errors, rather than simply attributing them to lack of language knowledge. Even a seemingly straightforward issue such as spelling can be complicated by strong cultural opinions. For example, because each chapter was written by a different author from a different country, it was decided early on to use each author’s preferred spelling in his or her respective chapter, whether American, British, or Australian. I had to study and recognize these spelling variations rather than insensitively correcting them according to American spelling.

However, my role as editor went beyond linguistic copyediting. Indeed, as Enkvist (1997) notes, “the text is the father of the sentence”; thus, sentence-level errors were edited out of necessity, but my focus was comprehensive editing for the organization, conciseness, and style of the chapters as a whole. Some of the common issues addressed in my editorial comments included unrelated information packed into paragraphs, under-supported or ambiguous assertions, redundant and repetitious passages, and inaccurate assumptions about audience knowledge. Each of these items had to be addressed in a way that conformed to the authors’ original strategies and purposes for their chapters, not by merely re-writing bulky sentences. One chapter, for example, discussed the effect of globalization on traditional African music. Styles of music from different nations were listed, but unless the audience shared the author’s local knowledge of African music, they were unlikely to understand the significance of the different styles or their effect on each other. This example, like many others, could not simply be “corrected,” but had to be highlighted by a diplomatic comment to the author, addressing the author’s purpose in discussing African music and providing suggestions on how to better meet that purpose.

While these issues are not unique to ESL texts, editing for them as part of this project provided a particular learning experience for me. One of the overarching challenges was achieving cohesiveness among the different chapters while maintaining the authors’ individual voices. As the readers’ advocate, my goal was to collaborate, not co-author. This process, again, required cultural awareness on my part, as the authorial voices of this project were much more diverse than those in other projects.

On the sentence level, this meant allowing unusual—yet clear and correct—phrasing to remain as a type of “written accent” rather than enforcing my own American accent (Harris and Silva 1993, 531). At the organizational level, this meant being aware of cultural expectations and communication norms, especially the differences between what Edward T. Hall (1976) terms high-context and low-context cultures. As a member of a low-context culture that tends to favor the direct and explicit, I had to recognize that an author from a high-context culture may not necessarily view ambiguous statements or unnecessarily exhaustive introductions as areas needing improvement. In the author’s culture, the “ambiguous” meaning may be implied and the indirect presentation expected. Thus, rather than dictate American structure, my editorial comments reminded authors of the different contexts and expectations their readers may have and the effect the current version of text may have on those readers’ ability to understand the authors’ arguments.

Providing such commentary, however, was a challenge in itself. Because idioms common to my culture may not make sense to those of another, my comments had to be specific and concrete in order to avoid confusion. I could not use the shorthand of figurative language. Conversely, rules of politeness rely on a measure of indirectness, especially in high-context cultures. Thus, if too direct, my comments may be perceived as rude. Balance was required in order for my comments to be both effective and diplomatic.

Despite these challenges, I found the project very fulfilling. Not only did it give me valuable experience as an editor and provide me with promising professional contacts, but it also stretched my abilities as a communicator and collaborator as I learned to respect and interact within a more diverse community of writers.

Finally, I express my sincere gratitude to the Technical Editing SIG for awarding me this scholarship. It is both a great honor and a relief as it enables me to take another step forward in my career.

References

Enkvist, N. E. 1997. “Why we need contrastive rhetoric.” Alternation 4(1): 188–206.
Hall, E. T. 1976. Beyond culture. Garden City, NY: Anchor/Doubleday.
Harris, M., and T. Silva. 1993. “Tutoring ESL students: Issues and options.” College Composition and Communication 44(4): 525–537.