What Style Guides Offer
Style guides don't make poor writers better, but they certainly are a step in the right
direction!
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.
Read IBMs Guide to Tech Docs
 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, and evaluating
technical information
Inspecting technical information
Testing information for usability
Testing technical information
Editing and evaluating technical information
Reviewing the visual elements
¡¡ |
