Do-It-Yourself Style Guides for All Occasions

By Miki Magyar

A style guide doesn't have to be massive and it's not just for manuals. It can be as simple as a one-page checklist for a particular type of document, or a template file on your computer. If you have a number of similar documents to create or edit, making a style guide can save a lot of time and energy, and improve the final product. While this is aimed at the writer working in a corporate environment, the independent contractor will find it applies, also. If you can offer your clients a style guide or template in addition to the documents you write or edit, they will be impressed with your professionalism.

What are style guides and why do you need them?

A style guide is a set of editorial decisions. Most large companies have style guides for their documentation/publication departments, to keep all their documents consistent. The typical style manual addresses the most common problems of grammar, punctuation, usage, and other conventions, and sets down the approved or 'right' way to write them. We are all familiar with the Chicago Manual of Style, Strunk and White, and other standards. However, even the best of these can't cover everything.

A good style guide serves several functions beyond insuring consistency: by establishing 'the rules' it saves having to re-make the same decisions over and over; it allows you to generate boilerplate and checklists more easily; it serves as an arbitrary external standard, which minimizes arguments; and it can be an effective tool for improving the quality of your documents. It can simplify the process of generating documents and speed it up. It makes it easier for others to contribute to a document. And most important of all, it saves wear and tear on the delicate nerves of editors.

Different guides address different levels of detail: general (Chicago, Webster's, Grammatik); specific to your company or department; or specific to a set of documents. They can be simple or complex, formal or informal. They cover content and format, and sometimes structure or organization (the order of sections in a manual, for instance).

But a style guide does not have to be a massive tome, and it's not just for manuals. It can be as simple as a one-page checklist for a particular type of document, or an annotated template file on your computer. Many documents can benefit from style guides:

A style guide is a formal set of decisions and instructions about format, content, etc. A template is an example of how to apply these decisions, as is a boilerplate file. Templates, boilerplates, and other fill-in-the-blanks documents derive from style guides, and may be implicit models of a style guide.

When do you need one?

Style guides are useful when the document goes out the door to customers, when content must be clear, or when confusion affects performance. If you have a number of similar documents to create or edit, making a style guide can save a lot of time and energy, and improve the final product. If you see several instances of documents which are all nominally the same kind, but each one looks different, you can use a style guide.

For example:
Your company has a style guide for its manuals, but Application Notes are done by individual engineers, and are all different.

You have a standard format for manuals, but no style guide, and the standard format doesn't work for the new product.

The Safety Manager says everyone has to have hazmat training, but each department has been using different training materials.

Management decides that the weekly discussion meetings are generating a lot of useful ideas, and want proper minutes taken.

Assembly instructions have been marked up by individuals to make their work easier. You now have fifteen different ways of assembling the same component.

If your company is applying for ISO certification or has a quality program, style guides will be invaluable in helping you create and maintain consistent required documentation. One of the most common causes of failure in the certification process is poor documentation or inadequate document control. Style guides can insure that all the documents have the required control information (date, revision, etc.) and content (authorities, revision history, etc.).

But don't create a style guide if it isn't worth the work. Remember that the purpose of a style guide is to make your life easier, not confine all writing to a straitjacket. Memos, notes, preliminary drafts, internal one-time documents etc. usually don't need to conform to any but the most general level of guide, such as a dictionary.

And remember that once you have a style guide, someone (probably you) needs to make sure that all the relevant documents conform to it. Be sure that this effort is worth it before you generate rules. It's like raising kids -- don't make rules you don't want to have to enforce.

This brings up the issue of control. It is generally easier if you keep the master copies and distribute working ones. People will quickly get used to the idea of editorial control if it's presented as a way to save them effort. If it makes more sense for some other department to keep control of a master document or style guide, make sure everyone knows who's responsible for maintaining it.

How do you make one?

The first step is to set your limits. Begin with a good dictionary and one of the excellent general style guides, such as the University of Chicago's A Manual of Style, as a general guide. Then you only need to specify items that are not covered in that reference. For specific fields, you may want to use ANSI standards or technical dictionaries. Whatever references you use, make sure that they are specified in your style guide, that copies are easily available to those who need them, and that everyone knows they are there and The Authority.

Unless you are assigned the task of establishing a corporate style guide, start small. Pick one set of documents to begin with. Start collecting examples of items you need to make decisions about. If a corporate style guide already exists, check it to see if it covers your examples, or if it should be revised. It may be easier to modify an existing guide than to start from scratch. Steal from the best. Look for good examples of style guides and copy what you like, avoid what you don't like.

Begin by finding good examples of the class of documents and specifying the components that aren't covered by a general guide. Include whatever is required. Make it explicit, concrete, and complete. The guide should be a set of directions on how to generate a 'correct' document. If the person writing the document follows all the specifications in the style guide, it should come out okay.

Typically, corporate or department-level style guides specify such things as:

type font and face for text, headings, captions, etc.
content and format of headers, footers, footnotes, etc.
how lists are formatted
rules for numbering instructions, sections, etc.
page margins
how graphics are placed and identified
spelling for specific words not in the dictionary
rules for capitalization
rules for different levels of headings
organization of sections in a large document

Write down your editorial decisions as they come up, and keep notes, or a draft copy that you add to. Organize and formalize it when it covers enough detail to be a useful guide. Could someone else use this to generate a 'correct' document? Try it and see.

There are a number of ways to organize a style guide, depending on how complex it is. A simple one can be both an example and specification in one. For instance, a guide for meeting minutes could be a page showing the layout, with each section explaining what it contains and demonstrating how to format it.

A more complex guide could be organized by content, format, and structure, or alphabetically by item. You can combine style guide and levels of edit into a checklist. At each step of the document development cycle, you fill out the checklist of which components have been verified at that level, and what style guide components have been used to verify them. For quality programs, this signed and dated checklist can serve as VOE (Verifiable Objective Evidence) of documentation quality control.

And of course, make sure your style guide is itself an example of everything in it, and follows its own rules.

How do you get people to use it?

Once you have your document specifications and editorial decisions, make a template model and get feedback from relevant parties on what they'd like to see improved. Pass it out on a trial basis to get people used to the idea that such a guide exists, and that they have an interest in seeing it used. Be sure to include Marketing – they may already have a ‘standard’ set of fonts and layouts they are using, even if not formalized.

If your company doesn't already have style guides, do it first, then ask for approval.

Most people like boilerplate files. If other people are going to be contributing to the document, it's easiest to have them use a template than to give them a style guide. Not only is it easier for them, but it's less work for you. If they've used the most current rev of the template, you can be sure that all the template formatting and content is correct, and doesn't need to be edited.

When you generate a template, be sure to modify the style guide and template together. Date them so you know that people are using the correct version. Use styles if your software allows them. It's an easy way to specify many formatting features. You can also include comment fields with instructions, and codes for search and replace. Include examples that explain their correct use. For example, the text of caution, warning, and note examples could explain when to use each one.

No document is perfect the first time, including style guides. You should expect a period of trial and error as you develop the guide. Only when you find out what incorrect assumptions you've made will you be able to fill in the gaps or leave out the obvious.

Once you have one style guide, it can serve as a model for all the rest. So be sure the first one has a long enough trial period that you are comfortable with the product. Select a font that fits the company, and use it consistently. Select a general page layout scheme that will be suitable for most of the documents in your company. The long-term effect of a good set of style guides is that everything that is generated look like it came from the same place, is easy to create, and easy to edit. And anything that makes life easier for the editor is a Good Thing.

About the author:

Miki Magyar is a semi-retired Senior Technical Writer in Boulder, Colorado. She has been documenting hardware, software, and systems for over 15 years. She taught technical communications at Metropolitan State College in Denver. As Communications Support Services, a consulting service, she offers training for technical professionals in communications skills and project management, in addition to contract writing and editing. She is active in professional organizations, and is a frequent presenter at conferences.

© 2005, Miki Magyar