Project Management 6: Establishing Quality Guidelines for Instructional and Communication Products (When to Accept Drafts and Deliverables and When to Reject Them)

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.

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:

  • Punctuation
  • 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
  • Headings
  • 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.

abc def ghi
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

Capitalization Punctuation
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:
    • Windows
    • Mac
    • UNIX
    • Other

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:

    • Hardware
    • 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.

Develop Templates

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:

  • State the three benefits of a word processor
  • Name two types of word processors

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:

  • Introductions
  • 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
  • Conclusions

The exact text that is common varies by information product.

2.   Determine the type font, emphasis, and size for:

  • Headings
  • Paragraphs (body text)
  • Examples

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
Printed
  • Weight and type of paper for the cover stock.  Paper weight refers to the strength of the paper.  The heavier the weight, the stronger the paper.  For paperback books, the typical cover is cardboard stock paper, about 100 pounds.

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.

  • Weight and type of paper for inside pages.  The weight of paper for a typical technical manual is 40 or 50 pound, for a marketing brochure, 60 pound.
  • Number of inks (if using any in addition to black). Adding a second color or third color ink to the page can enhance the appearance of a communication product, but also adds to the expense.  If you plan to use color photographs, you will need to use 4-color printing (this is the printing process that allows the reproduction of color photographs).
  • Binding.  Indicate whether you want the communication product shrink wrapped (wrapped in plastic), perfect bound (the cover wraps all around the front, back, and spine of the manual and the pages are glued to the cover), saddle-stiched (stapled), or drilled.
  • Anticipated number of pages.  The number of pages affects the choice of printing presses.  Printers use one type of press for jobs with fewer pages; a web press for jobs with higher numbers of pages.  The number of pages also limits your binding options.  For example, printers cannot use perfect binding if the manual exceeds a certain number of pages.
  • Anticipated number of copies.  Because the most expensive part of printing is in setting up the presses, printers usually offer price breaks for larger print quantities.  The printer can spread the cost of setting up the presses over more copies.  The more you print, then, the less the cost per copy.
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.

Advertisements

About idmodelsandprocesses

Exploring, reporting, teaching, and advising on learning and communication for the workplace and consumers. saulcarliner.wordpress.com
This entry was posted in Project Basics. Bookmark the permalink.

Please add to the conversation.

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s