Creating a Style Guide for Technical DocumentsEllen Perry
As a technical editor, you'd be wise to create a style guide for your writing group. A style guide is a time-saving resource that documents the guidelines for punctuation, capitalization, spelling and usage. Just those four categories may seem overwhelming at first — so much to be covered! But remember that a style guide is a living document; it's constantly updated, never truly finished.
To begin, decide if it makes sense to create your own style guide or adopt an existing one. Some technical editors adopt the Microsoft Manual of Style for Technical Publications (second edition) as their standard, and then they create a list of exceptions to that guide's rules. The downside here is that people must check two places for answers. If you decide to use this method, keep your list reasonably short. This article assumes you're creating your own guide.
Planning the Style GuideAs you plan the guide, research and answer these questions:
- Who's your audience? Freelance editors? Writers in your group? Others in the company who write about the products?
- Does your audience need examples for the style rules you set? Examples can drive home a style rule for readers.
- How will the style guide be produced? As a help file? On your company's intranet? As printed pages?
- How will you update the guide and get those updates to the guide's users?
- How will people access the information? Index? Search mechanism? (Don't rely solely on a table of contents.)
- Should people read the entire style guide, or should they dip into it only for specific answers? If you choose the latter, consider organizing your guide as an A-Z reference, the traditional organization for an in-house style guide.
- Does your company have people with vested interests in some style decisions? Consider meeting with them about controversial style rules or usage decisions.
- How does the localization of your technical documents constrain your style decisions?
Writing the Style GuideAs you begin writing the guide, document the standard topics that most style guides contain ("Capitalization," "Commas," "Bullet Lists," and so on). Keep your writing style extremely concise, and use subheads to organize the information for readers.
Use your style guide as a place to collect the correct spelling of feature names in your products. Is it "InfoCenter"? Or "infoCenter"? Or "Info Center"? These entries are quick to write and save writers a lot of aggravation.
Early in the development of the style guide, create entries about your group's biggest writing bugaboos. What do you correct over and over as you edit? For example, your writers may document procedures using inconsistent wording. Create an entry called "Standard Wording in Procedures" that defines wording for menus, dialog boxes, and so on. Here's an example from such an entry:
Standard Wording for MenusIdentify the menu at the beginning of the step with the phrase on the _ menu; use the verb click for items on a menu.
- On the Tools menu, click Options.
- On the View menu, click Toolbars -> Standard.
- On the shortcut menu, click Select All.
- Click Options on the Tools menu.
- From the View menu, choose Toolbars -> Standard.
Don't forget to ask the potential users of your style guide what they want in the guide. And provide a mechanism for getting feedback to you about the guide's entries (ones that are there, and ones that may be missing).
Build the style guide during your downtime, and add rules for troublesome terms during your crunch time. Writing a style guide may seem like a daunting task. But remember that each entry you add is a question answered for somebody and, quite possibly, time saved for you.
Ellen Perry is a lead technical editor at Autodesk, Inc. She coordinates the editing and indexing of the end-user and developer documentation for AutoCAD, a design and drafting program for architects and engineers.