Apple Releases Sept 2008 Style Guide

Hat tip to Daring Fireball (an excellent blog that I read despite not owning any Apple products) for the news that Apple has released its 2008 style guide.

When 1,000 writers are writing technical documentation for 2,000 products, consistency is very important, even down to the correct capitalization and noun strings used to refer to specific parts of software or hardware. Style guides keep everyone on the same page, so to speak, and help reduce confusion among customers when they read about "front panel objects" versus "front panel controls" versus "front panel nodes". Are those the same thing or are they different things? You, as the customer, should not ever have to wonder about this. The style guide helps mitigate these issues.

Of course this means that, as a writer, your range of expression is restricted. You cannot write everything the way you want to. There is very little room for creativity and personal style. You must submit to the whims of the company style guide. Some people find this situation constricting and frustrating. So it's important that technical writers have a say in how their style guide is constructed. It must not be an authoritative top-down mandate from on high. It must not change every two weeks at the whims of a tyrannical editor who decides that it's okay to split infinitives in January but not in March.

No, the style guide must be collaboratively constructed and able to be modified by anybody. If you have 1,000 writers in the company, you can introduce some representation into the process to make things easier; that's fine. Form a style guide committee comprised of members from different groups. Regularly rotate through representatives. Non-reps can submit their own issues (as bug reports) to the committee and argue for them in front of the committee, who will decide. Yes it sounds very, well, Congressional. And it takes a lot longer than simply deciding things. But style guides shouldn't change too often anyway -- that's one way to confuse and frustrate people. And if you're going to enforce a process on somebody, at least give them a say in how that process is constructed. You don't have to agree with their suggestions, but you do need to give them an avenue for dissent. Otherwise, all the little frustrations will build up, and the only opportunity to release those frustrations will be to quit (or move into Marketing!).

After all, you hired smart people, right? So put their intelligence to use.

And by all means, encourage new hires to look at the style guide. They will find all those weird little issues and inconsistencies that you never noticed because you've been dealing with the same document for six years.

Finally, remember that there's a reason it's called a style guide and not a style rulebook. There will be situations in which it makes more sense to go against one of the guidelines rather than blindly following the style guide. Recognize these situations and learn to make your case for why, in this case, splitting an infinitive is okay. Remember that the number one decider of any situation is "will this help the customer understand what we're talking about?"

Note here that I'm talking about style guides for technical writers. But my ideas could just as easily apply to coding conventions or "best practices" documents for programmers.