The Official Publication of the STC Technical Editing SIG
Michelle Corbin
The Boston Globe publishes a blog called “The Word Blog” where I discovered (via a Twitter post to this blog) an article
* about the placement of the word “only” in a sentence. It was fun to see the journalistic view of this grammatical construct (or nit, in the author’s words). Where do you fall on where only belongs in a sentence? Is it more than a nit in technical communication?
* http://www.boston.com/bostonglobe/ideas/theword/2009/11/who_moved_her_o.html
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.
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/.
Meredith Kinder and Vanessa Wilburn
The votes are in!
Congratulations to the STC Technical Editing SIG officers for 2010!
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.