Q: I’m setting up a Technical Writing Dept. for a Financial Services company. What is the best style guide to start out with? We have no internal guidelines. This will need to be useful for both beginners and also more experienced tech writers
A: The benefit of adopting a style guide is that it puts guidelines in place to ensure consistency across all documents you deliver. While style guides don’t make poor writers better, they’re a step in the right direction if you want to improve the quality of your documentation!
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 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 Style Guide for Developing Quality Technical Information
Extensive before-and-after examples, illustrations, and checklists, the authors show exactly how to create documentation that’s easy to find, understand, and use.
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.
What style guide do you use?