Product guidelines refer to the level of acceptable quality for content produced. They include:
- Editorial guidelines
- Technical Standards for Authoring
- Viewing guidelines
Establish Editorial Guidelines
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:
- Style guidelines, customs followed for spelling, capitalization, punctuation, usage, terminology, and typographical arrangements.
- Technical standards for authoring, which refer to the tools and minimum system requirements used for creating the technical communication product
- Templates are files used with a word processor, authoring tool, authoring system, or similar tool into which you put standardly used text and formatting.
- Production specifications, which indicate the instructions for preparing printed materials or distributing online materials
Together, these guidelines are called editorial guidelines. The next several sections explain how to set them.
Set Style Guidelines
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.
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:
then you shouldnot write telephone numbers like this in chapter 4:
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:
- Notations of scientific formulas
- Use of numbers (for example, do you write a large number as 1 million or 1,000,000)
- Citations from other sources
- Table of contents entries
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 PressOrMicrosoft Style Guide.|
|Most medical writing||Style guide of the Editors in the Life Sciences|
|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
- Standard wording for instructions and explanations
- Specialized uses of punctuation
- Specialized notations for scientific and technical formulas
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 table below shows an example of such a grid that was developed for this book.
|jkl||mno||pqrreaders, use the term users instead|
|stuusers, preferred term for readers||vwx||yz|
|HeadingsChapter titles use named style Heading 1[A] uses named style Heading 2[B] uses named style Heading 3
[C] uses named style Heading4
|ReferencesUsing APA 3 style||TablesUse MS Word Table Autoformat “Simple 1” designAdd inside borderColumn heads in bold, upstyle capitalization (initial cap first major words)||CaptionsCenteredUpstyleBold
Indicate the figure number (consecutive from beginning of the book)
Example of a Style Sheet That Documents Exceptions to the Style
Set the Technical Standards for Authoring
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:
- Authoring or desktop publishing software. This is the software that you use to actually enter the bulk of the communication product. You might use other software to help you with specific tasks, but this software is the one that you use to coordinate all of the pieces and from which you will produce your final product.
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 or a content management system|
|Online help||An online help authoring tool, which may work in conjunction with a full-function word processor or a content management system|
|Tutorials||Level 1 e-learning: Powerpoint capture tools, which let you record a soundtrack to a slide presentation and add some quiz questionsLevel 2 e-learning: eLearning authoring tools or tools provided by a Learning Content Management System, as well as video and audio production tools (if needed)Level 3 e-learning: Advanced web development tools, such as Flash, as well as specialized software like simulation authoring tools and custom programming|
|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, such as Flash|
|Web pages||A tool that lets you produce information in HTML or that can be read on any system, regardless of its hardware|
|Mobile content||A tool that lets you produce content as an “app”|
|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|
Although most authoring tools let you easily exchange files between systems, not all do. 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.
- Operating system used with the authoring or desktop publishing software: Indicate whether the operating system of your authoring tool runs under:
Although operating system incompatibility is minimal, some tools still only work with certain operating systems.
- Additional development software (only indicate if appropriate): Although authoring systems handle many common tasks, such as entering text, preparing graphics, and indicating jumps or links in online materials, they do not handle every task that you need to perform, or might not perform those tasks in a way that meets your needs. In such instances, you may purchase additional software to handle these special tasks. Following is a list of software that many technical communicators typically purchase in addition to the authoring system:
- Graphics package: Software for preparinge graphics, such as three-dimensional drawings, clip art (libraries of art that you can “clip” and paste into your communication product, and computer-aided design drawings
- Grammar checker: Software that can check some aspects of grammar and style of a communication product.
- For online information communication products, also specify the minimum configuration of a computer on which users can view the communication product. If you do not specify this, users will try to view the information on any available computer and the computer might not be able to display the information.
Specifically, specify the following:
- Operating system if this makes a difference. In addition to identifying the operating system, also identify the version of the operating system. You can use files created in one version with later versions of the operating system, but you cannot use files created in a later version with an earlier version of the software.
- Memory: indicate the minimum amount of main memory needed to display all of the information
- Storage: indicate the amount of space needed to store the communication product on the hard disk of the computer.
- Specialized graphics adapters needed: indicate whether the system requires specialized graphics adapters to efficiently display content, wa situation that affects content that has extensive graphics, video, and simulation.
- Display: indicate any special requirements for the monitor. Colors and other images are often altered between different monitors.
- Input device(s): indicate whether users are able to use a keyboard, mouse, joystick, or touch screen. Indicate all of the input devices that users may use; if you do not indicate it, users will not know that they can use it.
- Other, such as sound cards and other equipment needed to view (and perhaps, hear) the communication product.
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: 3 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:
- Text that is the same in every part of the document
- Formatting for headings, body text, examples, figures, and other text elements
- Running headers and footers
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:
1. From your information design, identify common text elements. Following are text elements that are likely to be commonly used within a communication product:
- Headings within reference sections
- Lead-ins to lists
- Instructions to users, such as instructions on tests in tutorials and on menus and dialog boxes in online communicaton products
- Syntax diagrams for computer commands
- Running headers and footers
The exact text that is common varies by information product.
2. Determine the type font, emphasis, and size for:
- Paragraphs (body text)
3. Following the instructions provided with your authoring software, create the template.
Establish Production Specifications
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|
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, DVD, jump drive). Note: If you are distributing on a DVD or jump drive, 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 DVD, as well as the packaging around it.|