This article explains how to prepare book elements. Specifically, it explains how to prepare:

• Front matter, which includes the cover, inside the front cover, title page, edition notice, table of contents, preface, and running headers and footer
• Back matter, including appendixes, glossary, reader's comment form, and back cover

Top

How to Prepare the Front Matter

Much of the front matter of a publication is standard and does not require "writing" per se. Instead, developing many of the modules in the front matter requires "preparing" the material. To do this, you often "fill in" some "blanks." In other cases, you assemble information that is probably already available elsewhere.

How to Prepare a Front Cover

The front cover is the first thing users see when they open a communication product. At the least, the front cover provides the title and publisher of the communication product. If the communication product is a proposal, the front cover also states the organization for whom the communication product was prepared. At the most, the front cover grabs the interest of potential users through creative ideas and effective design. It draws users to the communication product, and encourages them to open it and check it out.

When preparing a front cover, first find out whether your organization has guidelines for preparing a front cover. Many organizations do. These guidelines help the organization make sure that all of its publications look like they came from the same place. The guidelines usually tell you what information to include on the cover, where to place the information, and which graphical elements to use.

If you do not have such guidelines available to you, include the following information, as suggested earlier:

• Full title of the communication product
• Name of publishing organization
• If you are preparing a proposal, the name of the organization to whom you are presenting the proposal

When placing information on the cover, make sure you do so in an uncluttered way. The title should appear about one-third of the way down from the top, usually in a large type (24 to 36 point). The publisher’s should appear about one third of the way up from the bottom, usually in a medium sized type (14 to 20 point). The information can be centered or aligned on the right margin (called flush right).

Last, use design elements to draw readers in. Although no formula exists to ensure that the design will draw readers in, some proven techniques include:

• Color. In some instances, a bold color catches the eye. In other instances, muted colors attract the eye.
• Graphics. Graphical images can make a strong impression on readers and encourage them to read further. For example, the cover of Managing Your Documentation Projects (Hackos, 1994), another book in this series on technical communication, uses the image of a jigsaw puzzle. Even people who have limited experience with documentation projects will know that managing them is like piecing together a jigsaw puzzle.
• Catch words and phrases. Sometimes, when users see a term they are interested in, it catches their attention and spurs them to read further. For example, when Microsoft introduced Windows 95, many software publishers placed expressions such as "for Windows 95" and "covers Windows 95" on the front cover.

Top

How to Effectively Use the Inside Front Cover

Among the most overlooked parts of a communication product are spots that are often intentionally left blank because no one took the time to creatively use them. The inside of the front cover is one prime example. Presenting information on the inside front cover is optional, but can be an effective location for:

• Directing users to related products and services. For example, the inside front cover of a booklet about employment benefits might include the telephone number for the personnel or human resources department and a list of where to find commonly used forms, such as medical insurance reimbursement forms. Similarly, the inside front cover for software might direct users to a related software package.
• Directing users to less commonly used features of a product, features that users about user might not have thought about. For example, the inside of the front cover might list "Five Little Known Uses of VisiNet."
• Subtlety marketing related products and services. For example, the inside front cover of a software manual might tell users about training courses available and the availability of an online bulletin board service.

Because most communication products are intended for use after the sale of a product or for use within a specific company or organization, users are not expecting a marketing pitch. On the one hand, if they feel that you are trying to "sell" to them, they’ll resent your efforts. On the other hand, if users feel you are trying to provide them with helpful information, they will appreciate your efforts. When placing messages on the inside front cover, make sure that you provide information that users might actually feel a benefit from, rather than a blatant advertisement.

Although online information, videos, and audiotapes do not have inside front covers, they do have space that is intentionally left blank that you can use for a similar purpose. Installation of a software program often takes several minutes. As the system copies the software from a CD-ROM or diskette onto a hard disk drive, you can display similar messages. For example, Paradox for Windows displays a series of messages telling users about lesser used features of the software and about support services as the system installs the software.

Similarly, producers of audiotapes and videotapes often use time before and after the presentation to promote related materials and to provide related messages. For example, motivational videotapes often have advertisements about related videotapes.

Top

How to Prepare a Title Page

The title page is usually the part of a document that is visible to users. It confirms that they are reading the intended publication. In a printed document, the title page is the first page. The labels on diskettes, CD-ROMs, audiotapes and videotapes serve the same purpose. For example, if a CD-ROM is separated from its jacket, users can read the label on the CD-ROM to determine which jacket to return it to.

The title frame in a videotape, usually the first frame of the videotape, serves the same purpose as a title page, as does the restatement of the title as the first line in an audiotape.

Preparing a title page is similar to preparing a front cover of a communication product. As you would do when preparing a front cover, first find out whether your organization has guidelines. Many do. Like those for preparing a front cover, the guidelines for preparing a title page usually tell you what information to include, where to place the information, and which graphical elements to use.

If you do not have such guidelines available to you, include the following information on the title page:

• Full title of the communication product
• Name of the publishing organization
• If you are preparing a proposal, the name of the organization to whom you are presenting the proposal

As with the front cover, place information on the title page in an uncluttered way. The title should appear about one-third of the way down from the top, usually in a large type (24 to 36 point). The publisher’s name or organization should appear about one third of the way up from the bottom, usually in a medium sized type (14 to 20 point). The information can be centered or flush right.

Last, use design elements, such as color, shapes, lines, and graphics, to enhance the appearance of the page. Some organizations use the same design elements as those used on the front cover. Others create unique title pages. See Chapter 14 for more information on how to use design elements.

Top

How to Prepare an Edition Notice

The edition notice is a required part of any publication that provides a variety of legal information, which protects both you and your users. This information includes:

• The date and owner of the copyright. This notice is one of several measures that you take to protect you from unauthorized use and copying of your information.
• List of trademarked terms used in the publication. To prevent other companies from adopting their product names, many firms trademark names and phrases used in their business. For example, Kimberly-Clark has trademarked the name KleenexÒ and Microsoft has trademarked the name Windows 95Ò . Any time that someone uses these and other trademarked names in a communication product, that person must indicate that the term is a trademarked term the first time that the term appears and, somewhere in the communication product, state who owns the trademark. This must be done for terms that your organization has trademarked as well as those used by others. One good place to list all of the trademarked terms and their owners is the edition notice.
• Other disclaimers. Often, information published in a communication product is subject to change after publication. Disclaimers in the edition notice provide you with a legal right to change information.
• Related information, such as contact information for the publisher and any related support services.

In printed communication products, the edition notice usually appears immediately after the title page. In online help, the edition notice appears on the "About..." option of the help menu. In online tutorials, the edition notice appears on the title panel. Edition notices for audiotapes and videotapes are usually incorporated onto the labels that are affixed to the tape.

Tips for writing the elements of the edition notice:

• Copyright statement. The copyright statement uses the following wording, exactly as shown:

Ó Copyright	1996	ABC Printers, Inc.	All rights reserved.
Copyright symbol and the word copyright.	Copyright year.	Owner of the copyright.	The words, "All rights reserved."

• List of trademarked terms used in the publication. Trademarks come in three varieties: registered trademark (which is indicated with the symbol Ò ), trademark (which is indicated with the symbol Ô ), and service mark (which is indicated with the symbol (sm)). When indicating a trademark, you must use the appropriate designation. For example, Big MacÒ .

The recommended approach for indicating a trademarked term is:

1. Indicate all of the trademarked terms owned by your organization first, in the following order:
1. Registered trademarks
2. Trademarks
3. Service marks
2. Use the following recommended wording:
• For registered trademarks:

The following terms are registered trademarks of International Business Machines Corporation:

PS/2 and OS/2.

• For trademarks:

The following terms are trademarks of International Business Machines Corporation: ImagePlus and OfficeVision.

• For service marks:

The following terms are service marks of International Business Machines Corporation: ImagePlus and OfficeVision.

Check first, however, with the legal counsel to your organization to find out whether your organization has a preferred way of wording this information.

3. Repeat this process for all of the other trademarked terms in your communication product, indicating the names of the organizations that own the trademarks and the trademark names.
• Disclaimers. Disclaimer place limits on information provided in the manual and protect publishers from typical misunderstandings that might arise when users read a communication product. The actual disclaimers that you use depend on the situations you need protection from. Here are some sample disclaimers:
• About prices. Despite your best efforts to verify prices, they often change or might be misprinted. As protection, you might include the following disclaimer:

Prices subject to change without notice.

Prices provided for example purposes only. Actual prices might vary.

• About the availability of products and services. Sometimes, technical communicators provide information about products are services that are not available in every region where a communication product is distributed. As protection, technical communicators use disclaimers such as:

Not all products and services are available in every region. Check with your local distributor to find out whether a product or service is available in your area.

Information in the edition notice traditionally falls into a category called "the fine print," the type of information that is printed in a smaller type size. However, you certainly can publish this information in the same size type as the rest of the communication product. .

Following is an example of an edition notice.

Top

How to Prepare a Table of Contents

The table of contents is a required part that lists the major sections of an informaion product and, in so doing, shows the relationships among sections. The table of contents is one of the key methods that people use to locate information in a communication product. Users can scan the table of contents to get an idea of the material that a communication product covers and where that material is located.

The table of contents usually appears as a separate page in a printed document, as the "Contents" option that appears in online help, or on the jacket of an audiotape or video tape.

Most desktop publishing, authoring, and word processing software will automatically generate a table of contents for you if you follow one specific guideline when developing your document: whenever you type in a heading, you need to mark the text of the heading and assign it the appropriate named style as both a heading and its appropriate level. This process is called tagging headings. Chapter 7 discusses heading levels. By tagging a heading with its appropriate level, the system treats that heading appropriately when generating the table of contents.

Although the production of a table of contents is a "punch the button" activity, preparation of the table of contents requires additional effort. Some issues you need to consider when preparing a table of contents include the following:

• All headings must have effective titles. The titles must clearly state what the section describes.
• Headings at similar levels within a part of a communication product must be grammatically parallel.
• Only include the appropriate number of heading levels in a table of contents. Too much information overwhelms readers; this can even happen in a table of contents. Generally, tables of contents only list headings at levels 1, 2, and 3. If you feel that more detail might be appropriate, you might include two tables of contents; the first a "regular" and the second a "detailed" table of contents, which up to 5 levels of headings. In the book, Techniques for Technical Communicators, the authors provided two tables of contents. In his book Information Anxiety, Richard Saul Wurman provided an annotated table of contents, which contained paragraph-length descriptions of each chapter, in addition to several levels of headings.

In addition to these issues, you also need to verify that the system has properly generated the table of contents. Often, the page number provided in the automatic table of contents is incorrect. You’ll need to correct that problem using the information provided with your word processing or authoring software.

Top

How to Write a Preface

A preface is a required part of a communication product that describes the purpose, background, and scope of information within the product. Users scan the preface to determine whether the communication product it describes meets their needs. For example, a student might read the preface of a reference book to determine if it might provide the information needed for a class project. An instructor might read the preface of a new text to determine whether to assign the book for class.

To help users with tasks like these, a preface usually explains some or all of the following:

• Purpose, describing what the communication product is about
• Audience, describing who the intended users are
• Prerequisite knowledge, which lists information that users should already know before reading the communication product (if appropriate)
• How readers should use the communication product
• What readers need to have to use the communication product
• Other useful information about the communication product

Where you place the preface varies, depending on the document you are producing. Following are some of the choices available:

• Printed documents, at the beginning of the document
• Online documents, in one of these places:

• For self-contained communication products, in the printed package accompanying the document
• For online communication products that are part of a series, within the communication product. Provide users with an option called, "About this Document"
• Videos, on the video jacket

When writing a preface, include the following information. Note that the suggested headings are generic; you can tailor them to the needs of your communication product.

• Purpose, which explains what the document is about. Be brief; explain the purpose in 50 words or less. For example:

This Problem Determination Guide provides step-by-step procedures for identifying and solving problems with your computer.

• Audience, which explains who the intended users are. Be as specific as possible, including job titles and education levels when appropriate. For example:

This Problem Determination Guide is intended for system operators who have experience with starting, stopping, and interrupting jobs.

Note the mention of both a job title and job skills in this example. In some instances, the user might be performing the skills needed to use the guide but might have a different job title.

• Prerequisite knowledge, which explains what users should already know before reading the document (if such knowledge is needed). Explain the prerequisite knowledge in terms of skills users should have rather than as other documents users should read. List the other documents, as sources for learning those skills. Users can determine whether they need to read the prerequisite documents. For example:

Before using this Problem Determination Guide, you should be able to:

• Start and stop the system
• Start and stop application programs
• Operate the printer
• Enter JCL commands

This information is presented in The System Operator's Guide.

• How this Document is Organized, which tells users where to find information in the document. For example:

This Guide begins with an initial procedure to determine the exact nature of the problem. It continues with several specific procedures, each exploring a different type of problem, such as a hardware problem or a printing problem.

• Conventions Used in this Document or Instructions for Using this Document (both titles are used), which tells users how to use the document if the instructions are not self-evident. This section is especially useful for online documents, whose structures are not readily evident to readers. If instructions and conventions are not self-evident, however, you should re-examine their use. As one technical writer commented, "manuals should be like rental cars. You should be able to use them without another instruction manual."
• What Readers Need When Using the Communication product, which varies, varies, depending on the medium used for the communication product.
• Online documents should have a "Machine Requirements" section, identifying the hardware and software needed to run the document. Print this information on the outside of the software package rather than in the software; users need this information before they install the online document.
• Instructional materials (videos, workbooks, and computer-based tutorials) should have a list of all documents and other materials in the course so instructors can make sure they have all the materials needed. For example:

Special Instructions: You need the following equipment when taking this lesson:

• IBM-compatible computer
• Windows 98
• CD-ROM drive
• SVGA monitor
• Other useful information, which you use a as needed.

Although the preface contains information essential to users’ success in using a document, experience shows that few users actually read it. One of your challenges, then, is finding ways to encourage users to notice the preface. Some ways to accomplish this are:

• Printing the preface on the cover of the manual or of the package holding the document so users can't miss it
• Using eye-catching graphical devices, such as those described in chapter 14.
• Repeating vital information from the Preface elsewhere in the document

Following is an example of a preface for a videotape.

Top

Preparing Running Headers and Footers

Running headers and footers are text that run at the top (headers) and bottom (footers) that help users determine their location in the communication product. At the least, they contain a page number. You should have inserted these into your first draft. Pages can easily move out of order, otherwise. Although not actually part of the front matter, running headers and footers are a key book element to include.

At this time, you add information to the running headers and footers. The type of information you add varies, depending on the type of communication product you are producing:

Some full-function word processors an desktop publishing systems can automatically take a heading and place it in the running header or fotter. In other word processors and desktop publishing systems, you need to insert this information yourself. When doing so automatically, make sure that the system changes the title of the section used in a running header or footer when a new section begins.

Top

How to Prepare Back Matter

Back matter is a combination of material that is similar to the technical content and similar to the front matter. The first sections of the back matter, the appendices and glossary, are extensions of the technical content. The latter sections are like front matter and do not require "writing" perse.

Top

How to Present an Appendix(es)

Appendices are optional parts that present information which users might find helpful in understanding the technical content, but not essential to doing so. Appendices appear immediately after the last content section of a printed document, and as supplemental readings distributed with audio and video tapes. Online information does not have appendices.

You write appendices as you would write any other type of technical content; the only difference is its location.

Top

How to Prepare a Glossary

As mentioned earlier in this book, a glossary is a section that contains definitions of terms used in a technical communication product.

Writing a glossary involves the following:

1. Selecting terms to include. At the least, you should include all new technical terms introduced in the document, as well as common terms that have a unique meaning in the context of the technical information. At the most, you should include all terms that readers might encounter but whose definition they might not remembered.

   For example, the online help for OneCare uses the term journal to refer to a journal of database entries. Although users will likely have heard the term journal before, they might associate it with a financial journal rather than a journal of database entries. Therefore, it was included in the glossary.

2. Writing the entries. A glossary entry includes:
   1. The term. Highlight the term, preferably in boldface type.
   2. The definition. When possible, use the same definition used elsewhere in the document. This definition should clearly distinguish the term from similar ones.
   3. Optionally, a glossary entry includes:
   • Part of speech, telling users whether the term is a noun or a verb. This is especially useful information for terms that are familiar to users but are used in unfamiliar ways. Place the part of speech immediately after the term.
   • Examples, which clarify abstract terms and terms that are similar to others.
   • Synonyms. Related terms that users should also be familiar with. Begin the list of related terms as "See also." Make sure all of the "see also" terms are in the glossary.

   Note that glossaries differ from dictionaries. Glossaries only provide definitions of terms introduced in a document and present only the uses of those terms that are relevant to the document. Dictionaries provide more complete definitions, presenting all uses of a word.

   Following are examples of glossary entries. Note that the definition is highlighted in the following entry and that the first letter of the term is capitalized. You do not need to capitalize the first letters of terms but you should be consistent among terms. That is, if you capitalize the first letter of one term, you should capitalize the first letter of them all.

   Journal: (noun) a record kept by the computer of all changes made to the database between the time the database is opened and the time it is closed. If the system unexpectedly stops before you close the database file, the journal serves as a backup. The filename for a journal file is XXXXXXXX.jrn, where XXXXXXXX is the name of the database file that you were working on. The system automatically erases the journal when you close the database file. See also backup.

   Note the mention of a related entry.

   Copy: a command used to copy files. Use this command to copy a single file or a group of files.

   Note the synonyms included in the following example:

   Computer-based training: Training that students receive through a computer. Also called computer aided instruction, computer-assisted instruction, and computer-based instruction.

   Note the related terms in the next example. The list of related terms begins with the words "See also."

   Introduction: A paragraph or group of paragraphs at the beginning of a passage that grabs and holds reader's attention, presents an overview of the upcoming passage, and relates the passage to readers' needs. Also see formal introduction, grabber, and lead.

3. When you send the draft glossary for review, make sure that you call reviewers' attention to it. Reviewers often find nuances of meanings in definitions that you need to "tweek" before the descriptions are complete.
4. Prepare the glossary.

If you are preparing an online product, you can link the glossary definition directly to the body of the text. Authoring systems for online help let you directly link to the definition. You indicate to readers that they are linking to a definition by placing the term in lower case letter, colored text (usually green or blue), and a dashed underline beneath the text. For example:

Authoring systems for tutorials and demonstrations are usually less flexibile in permitting direct links to the definitions. These tools let you create a link to the entire glossary; users move through it until they find the term of interest.

Top

How to Prepare an Index and Links

As mentioned earlier in this book, an index is a required part of a most communication products that exceed 16 pages. In a printed communication product, the index is a section placed at the end of the document. In an online document, an index is more sophisticated: it includes an index of terms that users can search, as well as links among topics.

Because users assume that an indexes contains a comprehensive list of key terms used in the communication product, many typically consult the index first when looking for a specific piece of information. These users often assess the effectiveness of your communication product by their success in finding the desired term. If they find the term, as they think of it, they tend to be satisfied (assuming the information product provides the needed information). If they cannot find the term of interest, but do find a synonym, they're a little less satisfied. And if users cannot find the term of interest or a synonym for it, they're usually extremely dissatisfied. Your ability to anticipate the terms users might use to find information is key to your success at preparing an index.

Although full-function word processors and authoring tools have can perform the physical task

of compiling the index and assigning page numbers, or creating the links, a person must identify the terms to include in the index and the items that need to be linked online. That person can be you, or you can hire a professional indexer to identify the terms for the index or links.

The following sctions explain how to prepare an index and links.

How to Prepare an Index: Follow this procedure to prepare an index.

1. Go through each page of the information product. Identify the following:
• Key technical terms and concepts
• Names of:
• People
• Organizations
• Products
• Screens
• Fields
• Other communication products
• Names of key procedures
• Each major entry in a reference
• Terms used in the glossary

If you are using a full-function word processor or desktop publishing program, you might identify these entries in the file (a process called tagging entries) to create a first draft of the index. See the instructions for your word processor or desktop publishing program for instructions on tagging entries.

2. Review the list of entries and look for relationships and duplicatoins among the terms. When looking for relationships, you might specifically look for:
• Hierarchical relationships, where one term encompasses many others. For example, in the OnePlus User's Guide, the term patient records encompasses many other terms:

Patient records, definition of
Patient records, creating
Patient records, security of
Patient records, updating

You might combine entries that have a hierarchical relationship into a group of related entries, such as:

Patient records

creating
definition of
security of
updating

• Parallel. Some terms have a parallel relationship. For example, an issue related to the security of OnePlus is encryption. In such instances, you create a "see also" reference entry, which directs users to a related index entry. For example:

Security, also see encryption

If you are using a full-function word processor or desktop publishing system, you might consider revising these entries.

3. Consider alternate wordings of the same phrases in the index and add those to the index. For example, if you have an index entry called "patient records, creating," you might also like to have an index entry called "creating patient records."
4. Consider all of the synonyms that users might have for a given term. Add these terms to the index. But, rather than providing a page number where you present the information users are looking for, merely refer to the entry with the correct term. For example, users of OnePlus do not revise patient records, they update them. The index entry would be:

revise, patient records, see update patient records

5. Update the index to reflect the new entries.
6. Review the revised index and make additional changes.

How to Prepare Links: Preparing the links for an online document involves creating both an index, as well as a series of links.

1. Prepare the index.
   • Choose entries in the same way that you would prepare them for a printed communication product.
   • Rather than linking index entries to page numbers, link them to topics.

   When users choose an index entry, the system should automatically display the related topics.

2. Test the links to make sure that the intended topic appears when users choose it.
3. Prepare links between topics, if you are preparing a hypertext document. In such instances, for each topic, identify all related topics. Related topics include:
• Topics in the reading sequence, ones that precede the topic and ones that follow it
• Topics on related subjects; for example, a topic related to the security of patient records in the OnePlus system is the topic of overall system security
4. Program the links. Although you can place the link anywhere in the topic, the least obtrusive place is at the end of the topic, present a list of related topics. Too many links in the body of a topic disrupts the reading sequence for users: the links distract.
5. Test the links to make sure that the system displays the intended topic.
6. If needed, program additional navigational aids, such as a tool to help users return to the screen from which they jumped.

Top

How to Prepare a Reader’s Comment Form and Postage Paid Reply

A Reader’s Comment Form provides users with an opportunity to communicate their thoughts about a communication product with its authors. In some instances, the Reader’s Comment Form provides users with an opportunity to identify information that is incorrect. In other instances, a Reader’s Comment Form provides users with an opportunity to share their opinions about a communication product. Technical communicators use this feedback to determine how to more effectively develop future drafts of the communication product. In a printed manual, a

Reader’s Comment Form is a form at the back of the communication product. In an online document, the Reader’s Comment Form might be a printed form distributed with the software package or might be an electronic form that users can complete and electronically send. Reader’s Comment Forms for audio and video tapes are often printed forms distributed with the tape. For information about preparing Reader’s Comment Forms, see Chapter 9.

To encourage users to offer their feedback, most organizations include a postage-paid reply form with the reader’s comment form. Postage pay reply forms follow strict regulations provided by the post office. Contact your local postmaster for more information on how to prepare a postage-paid reply form. Printers can also provide assistance in preparing postage-paid reply forms.

Top

How to Prepare the Back Cover and the Inside Back Cover

The back cover and inside back cover are the two last parts of a communication product. Both are optional. Both the back cover and inside back cover are traditionally left blank, yet they can be used for the same purposes as the inside front cover. See the description of the inside front cover for ideas on how to creatively use these spaces

Top

models | processes | techniques | resources on i.d. business and management | home

(c) Copyright. 1999, 2000, 2001, 2002. Saul Carliner. All rights reserved.