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.