For writers, a style guide is an essential tool for ensuring consistency and clarity. When a company I am working for does not have an in-house style guide, I recommend the following style guides:
- The Chicago Manual of Style, 15th Edition. The CMS, which is the standard of the publishing industry and has a long and venerable history, is a well-loved manual that I’ve used through several editions. The CMS is available in hardcover, on CD, and as an online, subscription-based version. When a new edition comes out, I geek out and read through it to see what might have changed. If you have no other guide, this is the one to have.
- Microsoft Manual of Style for Technical Publications, Third Edition. (Currently out of print.) As a supplement to the CMS, because of its emphasis on computer-related terminology, I’ve followed the Microsoft Manual of Style since its inception back in the early Windows days. Some of the approved terms have changed (even flip-flopped) since those early days, and I only recently switched to the third edition, so you may note older style choices in my writing samples. However, I am always consistent, whichever style I follow.
- As an alternative to the Microsoft Manual of Style, some people prefer to use Sun’s Read Me First! A Style Guide for the Computer Industry (there’s a new edition coming out in November 2009).
- For Apple-based software, there’s the Apple Publications Style, which is free to view on the Web. Note that Apple has it wrong when it comes to the correct capitalization of Web and the separation of the words Web and site (as in, “this is my Web site”), though some day it may become the lowercase web by sheer weight of usage. (Microsoft has it right on both counts in their style guide.)
There are other style guides for general or specific purposes, such as Skillin and Gay’s Words Into Type, Strunk & White’s Elements of Style, and so on. I’ve read most of them, but the CMS and the MS Manual of Style are my favorites—though I have a life-long fondness for Fowler’s acerbic wit in A Dictionary of Modern English Usage (now just Modern English Usage).
Creating Style Guides
Style guides can become a hobby. I started writing my own first style guide in 1988 at Borland, where I asked a co-worker to present my idea of a Borland Technical Publications Style Guide (with my outline and some preliminary sections written) to the publications group. (I was brand-new to the group; I felt that having someone who was more established present the idea would prevent it from being vetoed just because of people didn’t know me.) The idea was seized upon eagerly and followed through with gusto, so it immediately became a group project that everyone was proud of.
I have since written a number of smaller style guides for various companies that did not have their own; my policy is to not repeat what is already in my favorite two style guides, but to instead supplement them with style choices that were specific to that company. (“Smaller” is relative; one of them was approaching 300 pages, was written, formatted, and indexed as a complete book, and covered everything from word usage to FrameMaker templates to policies and procedures for the publications group.)
It is pleasant to note that some styles I determined for myself and have been following for a very long time have crept into the software industry style guides. For example, I never liked wording such as “The software allows you to perform this action,” and have always instead used more respectful wording like, “Using this software, you can perform this action.” I’m not so arrogant as to think that others are following my lead; I just think I was ahead of the curve.
