Editor’s Note: The following piece, by Jean Hollis Weber, is part of our collection of “classics”–articles that stand the test of time no matter how many technologies come and go. Don’t forget to download the sample!
As a technical writer, you may be asked to develop a style guide for the hardcopy and online documents you produce. Sounds easy enough. After all, commercial style guides and, potentially, examples shared by your colleagues should provide enough information to get you started. In researching your task, though, you may find a variety of definitions and explanations of what a style guide is and why companies use them. What’s more, you many find that style guides don’t seem to have consistencies among them that can help guide you in developing one. This article provides information that will help you in planning and developing a style guide. You’ll find information about the purposes of a style guide and guidelines for what should (and should not) be included, whether to develop one or more style guides, and how detailed the style guide should be. At the end of the article, you’ll find a sample style guide outline (in PDF format) that illustrates many of the details discussed in this article.
What is a Style Guide, and Why Use One?
A style guide is a reference document that includes rules and suggestions for writing style and document presentation. Style guides often specify which option to use when several options exist, and they include items that are specific to the company or industry and items for which a “standard” or example does not exist through commercial style guides. The specific content in the style guide is not usually a matter of “correct” or “incorrect” grammar or style, but rather the decisions you or your employer or client have made from among the many possibilities. More specifically, style guides can serve several purposes:
- To ensure that documents conform to corporate image and policy, including legal requirements
- To inform new writers and editors of existing style and presentation decisions and solutions
- To define which style issues are negotiable and which are not
- To improve consistency within and among documents, especially when more than one writer is involved or when a document will be translated
- To remove the necessity to reinvent the wheel for every new project
- To remind the writer of style decisions for each project, when one writer works on several projects that have different style requirements
- To serve as part of the specifications for the deliverables, when writing for clients outside your company or when outsourcing writing projects
A style guide contains both rules (non-negotiable) and suggestions or recommendations (negotiable). Which items should be rules and which should be suggestions is a matter of opinion and corporate policy, though items that result from audience analysis and usability testing are more objective and thus more likely to be rules. Keep in mind as you’re planning and developing a style guide that it should be an evolving document. You don’t need to include everything on the first pass; add items as questions arise and decisions are made, or change items as you make new decisions to deal with changing situations. Additionally, be aware that developing a style guide can often turn into a major power struggle within an organization, if someone attempts to impose it on a group of people who are accustomed to working without one. If the writers and editors are involved at all stages, and if the development can be seen as a cooperative effort with clear benefits to everyone, then developing a style guide can be a productive experience and the document can take less time to produce.
What Topics Should Not Be in a Style Guide?
Before determining what you should include in the style guide, consider topics that should not be included. Although style guides can include a range of topics, these are often best included in separate documents: Process information (how we do things in this company or this department).Process information does not belong in a style guide, but it often ends up there because you need to have it written down, but no one in your company knows where else to put it. Style guides are intended to help writers to write and editors to edit; process information could go in a documentation plan, project specifications, or other project management document. What do I mean by process information? Some examples:
- Who is responsible for what and when (writer, editor, reviewer, manager, subject matter expert, graphic artist, and anyone else who might be involved).
- How many reviews are required, by whom, and at what stage of a document’s development?
- Which tools are to be used for specific purposes (page layout, help authoring, Web page development, graphics development, and so on)?
- Where are documents stored (in a directory on the network, for example)? What file naming conventions, document numbering, document version numbering, and so on are used?
Design information (what our documents should look like).Design information has traditionally been an important part of a style guide, but it is best provided in a separate document. Here’s why:
- Information content is increasingly being reused in a variety of situations and media, both hardcopy and online. The presentation of information is again becoming separated from the creation and maintenance of the content, as it was in the days of typesetters and layout artists–but with the addition of markup languages such as XML providing easier multiple-use capabilities.
- Design decisions may be made at a corporate level, with writers and editors required to follow those design decisions; or writers’ and editors’ work may be turned into books or Web pages by some other part of the company or an external organization.
- Because many technical writers continue to be responsible for layout as well as content, and deal with both at the same time (rather than sequentially), you might prefer to put some or all design information in a series of templates, rather than in a checklist-style document.
Design decisions that belong in a design guide or in document templates, but not in a style guide, include:
- Page size and margins, number of columns, offset style (if used), typefaces and sizes
- Bullet characters, including whether and when to use nonstandard bullet styles or more than one bullet style
- Whether list numbers in procedures have a period after the number
- Use of horizontal and vertical rules in tables of data
- Use of spot color for headings, bullet characters, and other navigation aids
- What file formats and resolutions to use for graphics
- Numerous other issues related to the appearance of the final product
Design decisions that directly affect writing and editing should go in the style guide; for example:
- Chapter and section numbering conventions
- Capitalization style for headings, vertical lists, figure and table captions, and other situations
- When to use various types of highlighting (e.g., bold or italics type)
- Explicit information on what to do about writing for single-sourcing
- Which template to use for which type of document, if writers are also responsible for layout
Grammar and Writing Tutorials. Too many style guides get turned into tutorials on grammar, spelling, and punctuation. When the style guide is intended to be used by people who are not professional writers, this emphasis is understandable, but still misplaced. It’s often a matter of tradeoffs between brevity (including only what’s needed for consistency) and completeness (when you know that the audience does not know the basics). I generally try to solve this problem by having a separate document for the writing tutorial, if one is needed. Remember that style guides are references, consulted when a question or problem arises, rather than books to be read as a training tool. Rationale for Decisions. I recommend including only as much information as required, and leaving out all the rationale for why specific choices were made. If necessary, include the rationale in a supplementary document, or separate the rationale from the specific style guide points. The less that writers have to read and remember, the more likely they will read and remember the important points.
What Topics Should Be in a Style Guide?
What topics, then, should a style guide include? Remember, the choices you record are usually not a matter of “correct” or “incorrect” grammar or style, but rather the decisions you or your employer or client have made from among the many possibilities. A style guide should include the answers to questions such as these:
- The version of English to use (American? British? other?), specifying any variations. For example, in Australia, when writing computer software documentation for the local market, it’s common to use Australian or British English but spell computer-specific terms (e.g., program or disk) in the industry standard way rather than the vernacular way (programme, disc). If your employer or client has a list of nonstandard words, include them in the style guide.
- The system of measurement to use (American? Imperial? metric?), specifying any variations (e.g., “dots per inch” in a metric guide) and whether conversions should be included in parentheses. If conversions are included, make sure to confirm them with an appropriate expert and to indicate how many decimal places the conversion requires for acceptable accuracy.
- Any reference materials (such as an industry style guide, a particular dictionary, the company’s design and process guides) to use, specifying any variations. Don’t reinvent the wheel when perfectly suitable wheels already exist; focus on the things that are unique to your company.
- Which template to use for each type of document.
- What document elements (e.g., title page, preface, table of contents, glossary, index, summary of changes, copyright information) are required, and what to include in them.
- Content of headers and footers, and what pages they appear on.
- Chapter and section numbering conventions to use, if any.
- What legal elements are required (copyright, trademark information), and what goes in them.
- Index style: How many levels? Page numbers (for books) on main entries if they have sub-entries, or not? Page ranges: When to use. General guidelines on deciding what goes into an index.
- Glossaries, bibliographies, footnotes, and references: What style, and when to use.
- Caution, danger, and warning notices: Wording and usage.
- The style of capitalization to use for headings, vertical lists, figure and table captions, and other situations.
- The style of punctuation to use for running lists and vertical lists.
- The minimum level of information to include in a particular type of document (e.g., conceptual information or procedural information).
- Content templates or outlines, where appropriate (e.g., corporate policy and procedures or online help topics).
- What information to include in specific topic types in online help, perhaps with examples.
- The style to use for cross-references or clickable links, both when cross-referencing (or linking) within a document and to other documents.
- Whether to use within-document navigational features such as a clickable contents lists at the beginning of a chapter or long Web page.
- Whether illustrations and tables always need captions, or under what circumstances captions are required. Whether captions should always be referenced in the text; if not, under what circumstances references are required.
- When to use various types of highlighting (e.g., bold or italics type).
- When to spell out numbers and when to use numerals; the use of commas, spaces, or other punctuation in numbers over 999.
- What to do about single-sourcing; for example, never say “see above” unless using conditional text so that phrase does not appear in online help.
- Word use (e.g., company-specific or product-specific terms; acronyms and abbreviations, preferred words, and words to be avoided).
- Writing style and preferred wording for common phrases.
- Acceptable jargon, and the spelling, capitalization, and hyphenation of names and terms.
- Abbreviations used, including in measurements.
- Revision bars: What style, and when to use.
- How pages are numbered (sequentially throughout, or by chapter).
- Special requirements for the audience (e.g., language or knowledge levels). For example: Whether the singular “they” is acceptable; any terms to be avoided, such as non-English abbreviations or words, or terms that your audience might find confusing or unacceptable.
Do You Need One Style Guide or More Than One?
Some organizations may need only one style guide that covers all of their publications, both hardcopy and online. Most decisions about writing style will probably be the same for all the work done by a publications department, but some details may vary. Most differences will probably be design issues. Product-, publication-, or client-specific style guides can supplement the main company style guide by recording any decisions made for a specific situation. For example:
- Your company style might specify sequential page numbering throughout a document, but a particular project might require numbering by chapter.
- Some documents (user guides, for example) might not have numbered headings, while other documents (engineering guidelines, for example) do use numbered headings.
- Some jargon might be acceptable (or required) in documents for one audience, but not allowed in documents for another audience. These differences should be clearly spelled out.
- Hardcopy and online documents may have some different requirements.
How Detailed Should a Style Guide Be?
A style guide can be as short as a single page listing variations from a commercially available guide or the main company style guide, or it can be quite lengthy if it contains detailed specifications of topic content. Many companies adopt a commercially available style guide such as The Chicago Manual of Style, and only note any additions or changes in the company style guide. Other companies summarize the most relevant points from a major style guide in the company style guide, because a small guide is more likely to be read. Exactly how detailed your company’s style guide should be depends on how much the styles deviate from those included commercial style guides, the types of information products your company delivers, and how many different elements those information products include. In developing a style guide, begin by exploring these aspects, and then plan what details the style guide should include.
Summary and Style Guide Example
Style guides include rules and suggestions for writing style and document presentation. Style guides often specify which option to use when several options exist, and they include items that are specific to the company or industry and items for which a “standard” or example does not exist through commercial style guides. As you develop a style guide, keep in mind that the specific content in the style guide is not usually a matter of “correct” or “incorrect” grammar or style; instead, it’s a compilation of decisions that you, your employer, or client have made from among the many possibilities. Style guides can be of any length and level of detail; however, they should exclude process and design information, tutorials, and decision rationale that are best included in documents separate from the style guide. Instead, the style guide should include only as much information as is needed to meet the particular goals of the style guide at your organization. The information in this article and the TechWhirl Technical Writer style guide example (in PDF format) should provide a good starting point for planning and developing a style guide.
Download: TechWhirl Technical Writer style guide example (PDF)
