Choosing the Right Style Guide

IBM's Handbook for Writers and Editors

How Style Guides Can Help Technical Writers

Style guides can improve the quality and presentation of documentation. They establish a layer of professionalism that may not have been there before. They also reduce arguments and loose cannons within the department, as the style guide becomes the acknowledged reference.

4 Points to Consider when Selecting a Style Guide

There are at least four points to consider when selecting a style guide.

1. The Reader

Consider who will read your documents and ask:

• What is their reading level?
• What is their expertise?
• What is their motivation to read your material?
• Where do they read, e.g. office, while commuting, at home?
• What style do they prefer, e.g. formal or informal?

If you have different groups of readers, explore which group requires the most attention, and which guide suits their needs the most.

2. The Publication

If you re producing one publication for the same readership, your task should be easy. However, if you're managing press releases, technical documents, web content and newsletters, one style guide may not meet all your needs... and using two could be confusing.

Most Fortune 1000 companies (with a variety of publications and audiences) use an industry standard style guide as their basic guide and write exceptions for different divisions.

For example, the Marketing Dept might use the standards in The Associated Press Stylebook and Libel Manual, but use The Chicago Manual of Style for other sections.

3. The Users

Editors value style guides. Difficulties arise when untrained staff members have to use the style guide when producing web content, reports, documents, etc. They find manuals hard to use, (tip: AP is probably the easiest) and often simply ignore them.

To resolve this, (for the non-trained writing staff) prepare a style booklet based on your main guide. Determine the most important style points and write examples in real-work sentences. Keep the booklet short and easy to read.

4. Your Preference

If you don't have a preference, test it. Check the most important style questions in the guides you're considering, and then edit an article using each guide. Look at the results and once you have selected your primary guide, keep the rest for reference as each have their specialist areas.

Then examine the site's purpose and outline the main sections (e.g. words people use to navigate) and the links within those heads. Test it before it goes online.

You can do this by writing the heads and links on Post-IT sticky notes and put them on a chart. Show the chart to sample users. Ask them how to get from one section to another.

IBM's Guide to Developing Quality Technical Information

IBM's documentation experts have prepared the definitive guide to developing outstanding technical documentation for the web and print. Extensive before-and-after examples, illustrations, and checklists, the authors show exactly how to create documentation that's easy to find, understand, and use.

Developing Quality Technical Information

Table of Contents

Part 1. Easy to use

Chapter 2. Task orientation
Write for the intended audience
Present information from the user's point of view
Indicate a practical reason for information
Focus on real tasks, not product functions
Use headings that reveal the tasks
Divide tasks into discrete subtasks
Provide clear, step-by-step instructions

Chapter 3. Accuracy
Write information only when you understand it, and then verify it
Keep up with technical changes
Maintain consistency of all information about a subject
Use tools that automate checking for accuracy
Check the accuracy of references to related information

Chapter 4. Completeness
Cover all topics that support users' tasks, and only those topics
Cover each topic in just as much detail as users need
Use patterns of information to ensure proper coverage
Repeat information only when users will benefit from it

Part 2. Easy to understand
Chapter 5. Clarity
Focus on the meaning
Avoid ambiguity
Keep elements short
Write cohesively
Present similar information in a similar way
Use technical terms only if they are necessary and appropriate
Define each term that is new to the intended audience

Chapter 6. Concreteness
Choose examples that are appropriate for the audience and subject
Use focused, realistic, accurate, up-to-date examples
Make examples easy to find
Make code examples easy to adapt
Use scenarios to illustrate tasks and to provide overviews
Set the context for examples and scenarios
Relate unfamiliar information to familiar information
Use general language appropriately

Chapter 7. Style
Use correct grammar
Use correct and consistent spelling
Use consistent and appropriate punctuation
Write with the appropriate tone
Use an active style
Use the appropriate mood
Follow template designs and use boilerplate text
Create and follow style guidelines

Part 3. Easy to find

Chapter 8. Organization
Organize information into discrete topics by type
Organize tasks by order of use
Organize topics for quick retrieval
Separate contextual information from other types of information
Organize information consistently
Provide an appropriate number of subentries for each branch
Emphasize main points; subordinate secondary points
Reveal how the pieces fit together

Chapter 9. Retrievability
Facilitate navigation and search
Provide a complete and consistent index
Use an appropriate level of detail in the table of contents
Provide helpful entry points
Link appropriately
Design helpful links
Make linked-to information easy to find in the target topic

Chapter 10. Visual effectiveness
Use graphics that are meaningful and appropriate
Choose graphics that complement the text
Use visual elements for emphasis
Use visual elements logically and consistently
Balance the number and placement of visual elements
Use visual cues to help users find what they need
Ensure that textual elements are legible
Use color and shading discreetly and appropriately
Ensure that all users can access the information

Part 4. Putting it all together

Chapter 11. Applying more than one quality characteristic
Applying quality characteristics to task information
Applying quality characteristics to conceptual information
Applying quality characteristics to reference information
Applying quality characteristics to information for an international audience
Applying quality characteristics to information on the Web
Revising technical information

Chapter 12. Reviewing, testing, & evaluating technical information
Inspecting technical information
Testing information for usability
Testing technical information
Editing and evaluating technical information
Reviewing the visual elements

Other Style Guides For Technical Writing

I recommend the IBM style guide as I use it and believe it’s the best out there, especially for technical writers. But, for those starting out, maybe it’s too detailed.

Two other style guides are:

and

What style guide do you use?