Style, design, and process guides

This article has been revised and included in Developing a department style guide. It is included here for archive purposes only.

Style guides often contain three types of information:

• Process (how we do things in this company or this department)
• Design (what our documents should look like)
• Style (contents)

I don't think process information belongs in a style guide, but it often ends up there, probably because the someone needed this information written down, and no one knew - or could agree on -- where else to put it.

Whether design information belongs in a style guide depends on several factors, which I'll discuss later in this article.

Style information can be suggestions (and examples) or rules; many style guides are a mixture of the two. Which items should be rules and which should be suggestions is a matter of opinion and corporate policy.

Each of these documents can serve more than one function:

• Educate new hires (staff or contractors)
• Improve consistency within and among documents, especially when more than one writer is involved
• Remove the necessity to "reinvent the wheel" for every new project

Process guides

Process guides include such information as:

• Who is responsible for what and when (writer, editor, reviewer, manager, subject matter expert, graphic artist, and anyone else who might be involved). For example, who approves a project and its budget; who needs to sign off on a project; how many reviews are required and at what stage of a document's development; who reviews a document and for what; and so on.
   
• What's the timeline? (For example, at what stage of development are reviews held?)
   
• What procedures are to be followed to initiate a project, call a review, etc? Other planning issues. Tools to be used.
   
• Where are documents stored (in a directory on the LAN?), file naming conventions, document numbering (equivalent to ISBN), document version numbering, check-out and check-in procedures, etc.
   
• What type of information is to be included in a particular information unit? For example, what goes in a user's guide or a reference manual or online help?
   
• How to use tools to fit in with the company's other processes; for example, what file formats and resolutions to use for graphics.

Design guides

While I think "design" is separate from "style" I appreciate that both types of information might be best presented in one document. For example, when outsourcing a writing project, you might want to specify quite clearly the "look and feel" of the documents as well as their content, either before letting the contract or sometime during the planning stage. (This could be initiated by the contractors, who would want agreement from you for the expenditure to be involved in producing the docs, or it could be initiated by the company for which the docs are being written, if they know exactly what they want.) It's not really any different with inhouse projects.

Some of these factors determining whether design information should be included in a style guide, and what sort of design information is needed, include:

• What publishing medium are we using -- paper? web? online help? other? all of the above?
• Do we need to fit into a corporate style?
• Who is responsible for design and layout -- the writer? an in-house designer? someone else?

With the increasing use of markup languages (XML, for example; or even HTML with style sheets), the presentation of information is becoming separate from the creation and maintenance of the content of that information. Information content is increasingly being stored in databases for reuse in a variety of situations and media. (Markup languages are nothing new - they were here long before DTP and WYSIWYG.)

Design decisions may be made at a corporate level, and technical writers may be required to follow those design decisions (for example, font size and face; offset, two-column or other presentation; use of horizontal rules) or their work may be "typeset" by some other part of the company. This is, of course, typical of the publishing industry, but unfamiliar to many people who work in other industries.)

So someone, somewhere, should have a design guide that covers the work you're doing. What level of detail you need to pay any direct attention to is another matter. If you are responsible for the final layout of the document you are working on, then you need to be familiar with (and follow) the design guide in detail. If you are not responsible for the layout, you may not need to know much about the design - except as it may constrain the way you are writing or the illustrations you may be producing (or asking the graphics people to produce for you). A style guide is an appropriate place to put design information that crosses disciplines.

Here are some items that might be design or might be style:

• Headers and footers: what goes in them and what pages do they appear on?
• Chapter and section numbering conventions

Style guides

Having said what I think does not belong in a style guide, what do I think should be there?

• What version of English to use (American? International?), specifying any variations. For example, in Australia, when writing computer software docs for the local market, it's common to use Australian English but spell computer-specific terms (such as program or disk) in the industry standard way rather than the generic way (programme, disc).
   
• What system of measurement to use (metric? American?), specifying any variations (those pesky "dots per inch" etc) and whether conversions should be included in parentheses.
   
• What if any reference materials (such as the Chicago Manual of Style or the Microsoft Manual of Style, a specific dictionary, any industry specific style guides) are to be used, specifying any variations.
   
• What style of capitalisation is to be used for headings, vertical lists, figure and table captions, and other situations.
   
• What style of punctuation is to be used for running lists and vertical lists.
   
• Required document elements (for example, title page, preface, table of contents, index, revision history, summary of changes, copyright information) and what goes in them.
   
• What minimum level of information is to be included in a particular type of information unit (eg conceptual information, procedural informaion)? Where appropriate (eg online help), include content templates.
   
• Style for cross-references within the document and to other documents.
   
• Illustrations and tables: do they always need captions? If not, under what circumstances do they need captions or not? Should they always be referenced in the text? If not, under what circumstances?
   
• Use of highlighting (bold, italics).
   
• Numbers - when to spell out, when to use numerals.
   
• Word use (for example, press, select, type, click; see or refer to; company-specific or product-specific terms; abbreviations and acronyms).
   
• Caution, danger and warning notices: wording and usage.
   
• Index style: how many levels? (for book) page numbers 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 and bibliographies; footnotes.
   
• Revision bars: what style, when to use.
   
• How to indicate and acknowledge trademarks.
   
• When to use screen captures.

Too many style guides get turned into tutorials on grammar, spelling and punctuation. When the style guide is used by people who are not professional writers, as well as those who are, this emphasis is understandable. It's always 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 section for the writing tutorial, if one is needed. Separate documents might be better, on the theory that a small guide is more likely to be read.

---