Developing a Style Guide

Style guides explain the content, format, and purpose of the documentation that a Documentation department, or even an entire company, produces. Style guides can be finely detailed or purposefully vague. The kind of guide you create will depend on personal preference, the number of people who will use the style guide (the more people the more exact your style guide should be), and the nature of the products or services you're documenting. My personal preference is for a style guide to include only key details and to leave other details to the discretion of the writer, and so this article provides tips for creating such a style guide. This article covers the following topics:

Something to Keep in Mind
Things to Include
Things to Exclude
Wrap Up

Something to Keep in Mind

You should be flexible about enforcing a style guide. Documentation is not about enforcing styles with draconian precision. It's about delivering the right information to the people who need it. A strict enforcement of a style guide can lead to situations in which good information is bent to fit the mold, or even left out entirely. Such a situation devalues your documentation and ignores the needs of your users for a blind devotion to format. I've seen it happen.

To this end, your style guide should be flexible enough to allow for innovation while still being strict enough to enforce consistency. While consistency is an incredibly important aspect of documentation, and of any product for that matter, it is not the only aspect of documentation. There is also accuracy and adequacy. Don't forget that when developing and enforcing a style guide.

Things to Include

The following is a list of some things to include in a style guide.

Purpose of your documentation, including target audience. There are many different kinds of information and numerous ways to present that information. You should define the kinds of documentation you are going to produce and the information each kind of documentation includes, such as how-tos, quick starts, technical overviews, or end-user documentation.
Structure of your documents based on the kinds of documentation you're creating. You should include the same kinds of content, preferably arranged in the same order, across all of your documents. This doesn't mean that if information doesn't appear in one document you can't put it in another document. Nor does this mean that you should stretch, or invent, information so that you include everything that is "required." This simply means that your document design should be flexible enough to account for unforeseen needs.
Tone of your documentation. Will it be chatty, conversational, or formal? Tone has dictates both grammar and style. I opt for a conversational tone, especially for GUI documentation that is written for end-users. You and your department may opt for something different. You should always pick your tone based on your users and their needs.
Format specific to your documentation, such as font choices, when to use bold, and when to use italics. These are rules that should be kept consistent across all of your documentation because users will come to rely on these visual cues. You don't have to spend much time on this; there are some generally accepted "standards" that appear in many different kinds of documentation. Published style guides, such as the The Microsoft Manual of Style for Technical Publications, or Read Me First A Style Guide for the Computer Industry, can give you ideas about the kinds of format issues to address. But remember to keep things simple. Limit a format change to a single purpose and limit yourself to about three or four format changes for all of your documents. There's nothing worse than a menagerie of formats sprinkling a page.
Templates. You should always use templates for all of your documentation. Yep, I said, "Always." A properly set-up and enforced template ensures all documents have the same look and feel. Templates also remove a writer's need to think about format and allow writers to concentrate on content. Another advantage of templates is that if, at some time down the road, you decide to change format, all you need to do is change the template, and all of your documents will automatically update. This, of course, depends on the software you're using and how well you set up the template.
Standard content. Include any information that appears in several or all of your documents, such as introductory paragraphs or chapters, boiler plate information, or glossary terms. Doing this makes it easy for writers to keep content consistent.
Minor grammar points, such as whether you will say "on the form" or "in the form," and "click on the button" or "click the button." These minor grammar points won't have an impact on how useful your documentation is, but they can annoy a reader when they are inconsistent.

Things to Exclude

The following is a list of some things to exclude from your style guide.

Grammar is important, but leave it out of the style guide. Leave your grammar decisions to another source, such as the The Chicago Manual of Style, the MLA Handbook, or the The Associated Press Stylebook and Libel Manual. Using another source has two benefits. First, it leaves less room for writers and editors to argue about grammar. Second, you can use the time you would have spent debating grammar rules actually writing documentation. Which existing guide you should use is up to you. In the grand scheme of things, they're all pretty much the same anyway.
Departmental procedures and policies. Those should go into a Department Handbook.
How-tos for the software you are using. While it's a good idea to keep track of workarounds that your department has discovered, they don't belong in a style guide.

Wrap Up

This article provided a few tips on creating a style guide all written with my own biases. I feel that any style guide should provide enough guidance to a writer to minimize differences in writing styles but shouldn't be so strict as to limit the writer's ability to include or arrange information in a way that is appropriate for a particular product of document.

Creating a style guide is an exercise in compromise and self restraint. The grammar/style police out there have to lighten up and let the writers make their own judgments about content. The free spirits out there have to give up some of their creative freedom for the sake of the user. Such compromises aren't about proving who is right or wrong, but about doing what's best for the people who are going to be reading your documents. The style guide should act as a guide to help make decisions about what's best and not become your department's dead dogma.