Designer's
Toolkit
How to Set Editorial and Other Product Guidelines
models | processes
techniques | links
resources
on i.d. business and management
home
|
Designer's
Toolkit
|
models | processes |
In this Article |
Manufacturers establish "tolerances" for the products that they manufacture. These toleraces state the requirements that each product must meet. For example, the actual dimensions of a part must be within a certain percentage and the part must successfully pass certain tests during the manufacturing process. Manufacturing engineers call these tolerances quality standards.
Technical communicators establish quality standards in much the same way: tolerances for the products we manufacture. Instead of referring to dimensions and manufacturing tests, however, our quality standards refer to:
Together, these guidelines are called editorial guidelines. The next several sections explain how to set them.
Should each list item end with a period or not? Should the device above the system unit be called a monitor or a display? Should periods or dashes separate the parts of a telephone number? Should network only be used as a noun or can it be used as a verb?
The correct answer to all of these questions is that you can do whatever you want.
Really.
But whatever you choose to do, you need to do it consistently throughout the communication product. If you end list items with periods in chapter 1, then you should end them with periods in chapter 5. If you write telephone numbers like this in chapter 1:
(612) 555-6587,
then you shouldnot write telephone numbers like this in chapter 4:
612.555.6587.
The inconsistency resulting from an oversight on your part might confuse readers. They might not recognize the second version of the number as a telephone number because they previously saw telephone numbers presented in a different format.
Issues like these are called style. According to Webster’s Third New International Dictionary, style refers to the customs followed for spelling, capitalization, punctuation, usage, terminology, and typographical arrangements. All elements of style are choices, and technical communicators often follow different styles in different situations. For example, certain clients have their own styles and certain types of communication products follow a certain type of style.
Because the number of choices can be overwhelming and because most business communication follows a relatively standard style, most technical communicators choose a few key sources as references on all matters of style. When a question arises, communicators consult the appropriate source.
Similarly, when editors review your technical communication products later in the process, they can make sure that you followed the suggestions in the sources and indicate to you those instances in which your work deviates from those suggestions.
The reference addressing spelling and usage is called a dictionary. Most of you probably learned to use a dictionary as part of your early schooling. The reference all other matters of style is called a style guide. Fewer people have experience using a style guide. The Sidebar, Using a Style Guide, suggests how to use a style guide.
When you establish the guidelines for a project, one of those guidelines is the editorial guidelines. When setting editorial guidelines, you identify the dictionary and style guide you intend to use.
Dictionary: Dictionaries serve as your primary authority on spelling and usage. They come in two varieties: descriptive and prescriptive. A descriptive dictionary documents the way language is practiced in use and offers advice on spelling and usage based on common use. An example of a descriptive dictionary is Webster’s Dictionary.
A prescriptive dictionary suggests the best way to use language and offers advice on spelling and usage based on the way language should be used, which sometimes differs from the way language is used. An example of a prescriptive dictionary is the American Heritage Dictionary.
For example, a descriptive dictionary would list the word input as both a noun and a verb because, in use, input has both uses. In contrast, a prescriptive dictionary would only list the word input as a noun, because its use as a verb is questioned by language authorities.
Style Guide: A style guide addresses most other issues of style, such as:
Different style guides have emerged for different purposes. Some of the most common:
| For This Type of Technical Communication Product | Technical Communicators Typically Use this Style Guide |
| Most technical manuals and scientific reports | The Chicago Manual of Style, published by the University of Chicago Press. |
| Most medical writing | Style guide of the Council of Biology Editors |
| Most technical reports for the social sciences | The American Psychological Association (APA) Style Guide. |
| Most marketing and employee communications materials | One of the style guides developed for use by journalists, such as The Associated Press Style Guide and The New York Times Style Guide. |
Before Choosing a Dictionary and Style Guide: Before you choose a dictionary and style guide, however, find out whether your client already has a preference. Many corporations have a chosen style guide for use in particular situations. For example, one large computer manufacturer follows The Chicago Manual of Style for its technical communication products and The New York Times Style Guide for all of its marketing and employee communications products.
Similarly, before preparing an article for a scientific journal or trade publication, check their Guidelines for Authors. These Guidelines identify the stylistic conventions that the journal or publication prefers. Most journals print the Guidelines in each issue. Most trade publications send Guidelines to Authors upon request.
Exceptions to Information in Dictionaries and Style Guides: Despite their comprehensive nature, most dictionaries and style guides cannot address all of the issues that might arise as you prepare a technical communication product. Sometimes, the exceptions apply to all products produced by a particular organization and sometimes the exceptions apply to a specific project.
In these instances, you need to document the exceptions. At the least, you have some written reference when questions arise in the future. At the most, your editor can use this information to make sure you consistently followed the exceptions in your information product.
These are common situations in which you can expect exceptions to the dictionary and style guide:
Terminology for the specific project that you are working on, that might not be covered by the dictionary or that might require more specific uses of terms than covered by the dictionary
In her book on copyediting, Ann Judd suggests a simple means of recording changes to the style. She suggests taking a sheet of paper and dividing it into a grid, then marking the changes to the style in the appropriate block. The folllowing figure zhows an example of such a grid that was developed for this book.
| abc | ghi | def |
| jkl
|
mno | pqr readers, use the term users instead |
| stu users, preferred term for readers |
vwx | yz |
| Headings Chapter titles use named style Heading 1 [A] uses named style Heading 2 [B] uses named style Heading 3 [C] uses named style Heading4 |
Capitalization | Punctuation |
| References Using APA 3 style |
Tables Use MS Word Table Autoformat "Simple 1" design Add inside border Column heads in bold, upstyle capitalization (initial cap first major words) |
Captions Centered Upstyle Bold Indicate the figure number (consecutive from beginning of the book) |
Example of a Style Sheet That Documents Exceptions to the Style
Authoring refers to the task of entering text and graphics into the computer. But which computer? What type of hardware? What software? The appropriate choice depends on a variety of factors, such as your budget, the type of communication product you are developing, and your need to exchange files containing the communication product with other people.
Although you needed to use a system to create your information design and sample section, you can now make a more informed choice about the software and hardware needed to actually develop your information product. Specifically, you need to make these decisions:
The capabilities of authoring software change all of the time and keeping up with these capabilities could easily consume most of your time. With that disclaimer in mind, the best way to choose an authoring tool is to first consider the purpose of your communication product, then choose a tool that best meets the needs. Here are suggestions for generic types of authoring systems; when you need to make a choice, check the products currently on the market.
| For this type of situation | Use this type of tool |
| A brochure, flyer, or manual under 50 pages | A full-function word processor or a desktop publishing system designed for smaller documents |
| A manual over 50 pages | A full-function word processor or desktop publishing software that handles large documents |
| Online help | An online help authoring tool, which may work in conjunction with a full-function word processor |
| Tutorials | Authoring system designed for computer-based training, usually involves working with icons on a screen |
| Online demonstrations | A time-based authoring tool that usually involves orchestrating a number of elements (sound, text, visuals) to appear at certain times in the presentation |
| Web pages | A tool that lets you produce information in HTML or that can be read on any system, regardless of its hardware |
| Online and printed copy both | A tool that lets you "single source" documents; that is, that lets you create one documents that can either be printed or viewed online |
These days, many authoring tools can be used with several different types of hardware: Windows, Mac, and Unix. These tools also let you exchange files. If you are working in an organization in which you need to exchange files between different types of computers, you should make sure that your authoring tool lets you do so.
Specifically, specify the following:
Suppose that you are developing a tutorial. Your design indicates that the first screen of each lesson looks like this:
About this LessonWhat You Should Learn: After taking this lesson, you should be able to:
Time Needed: Indicate time in minutes. |
The headings are the same on the first screen of each lesson, as are the words, "After taking this lesson, you should be able to." You certainly could type this information as you begin writing each lesson. But why should you? The keystrokes duplicate keystrokes you have already taken and, more importantly, each time you re-type the same information, the more chances you have for doing so in error.
Templates are the tools you use to save this commonly used information. A template is a special type of file that you can use to consistently develop similar types of information modules and that you can use to reduce the amount of time needed to create a communication product. Typically, templates are files used with a word processor, authoring tool, authoring system, or similar tool into which you put standardly used text and formatting.
Templates typically contain the following information:
Although the technical instructions for creating templates vary among authoring tools, the following procedure suggests how you might determine which templates to create and which information to include in them:
The exact text that is common varies by information product.
Following the instructions provided with your authoring software, create the template.
Suppose you are preparing a user’s guide. What size will it be? 8.5 x 11 (a standard in North America)? A4 ( a standard in other parts of the world)? Will type of paper will it be printed on? Lightweight paper that’s inexpensive or strong paper that’s more durable (and more costly)? How will the paper be coated? A matte finish (dull) or glossy? How many color inks will you use on the pages? Just black or black with spots of other colors? How will you bind the guide? Will you punch holds in the side and expect users to insert it into a loose leaf binder or will you glue the sides together and wrap a cover around it? And speaking of the cover, what will it look like? Will you use a heavier paper than used for the rest of the information product?
The answers to these questions form the basis of production specifications, which describe how the communication product will look when it is produced. For printed materials, production specifications refer to the printing and binding of the communication product. For online communication products, production specifications refer to the means of packaging and distributint the material.
Specifically, consider the following issues when stating production specifications:
| Type of Communication Product | Issues to Specify |
| Printed |
Paper type refers to the finish of the paper. A matte paper has a dull finish, but holds ink better. A glossy paper has a shiny finish and shows off photographs and other illustrations better. You might also indicate whether you want to use recycled paper. Using recycled papers sends a strong environmental message to your customers. Note, however, that some recycled papers do not hold ink as well as new paper and that some recycled paper is more expensive to use than new. |
| Online | Means of distribution (server, diskette, or CD). Note: If you are distributing on diskette and CD, also specify the printing specifications for jacket covering the materials. (Same as that for other printed communication products). These specifications cover the labels placed on the CD and diskette, as well as the packaging around it. |
models | processes | techniques | resources on i.d. business and management | home
(c) Copyright. 1999, 2000, 2001, 2002. Saul Carliner. All rights reserved.