Technical Editors' Eyrie Photo of Osprey
Resources for technical editors Home page About technical editing Books Tips, techniques and checklists Links to other resources Newsletter archives Site index Search this site Business basics: marketing, website development, and more

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:

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:

Process guides

Process guides include such information as:

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:

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:

Style guides

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

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.