Training Manual Template Guide

Instructions on creating and maintaining a training manual based on Training’s FrameMaker template

Memec LLC • Training and Development Department• San Diego, CA

Copyright
Memec Training and Development Department, San Diego, CA © 2002 by Memec LLC All rights reserved

Confidentiality Notice
The contents of this manual are exclusively for the use of the employees of Memec and its subsidiaries. The information contained herein is proprietary and confidential. It may be shared with outside parties only after authorization by one's manager.

Revisions
Book Filename: TemplateGuide.book Location of Project Files: P:\Training\ERP Documentation\01_WiP\Training Manual Template Guide
Revision No. 1.0.0 1.1.0 Date 6 August 2002 4 September 2002 Description Initial release Minor content revisions: addition of Table & Figure cross-reference formats; supplemental comments to Naming Files section; change in Revisions page. Minor content revisions: updated index and added section on document revision numbers. Changed format and method for handling notes, cautions, and tips. Deleted “Other Chapter Elements” section and moved “Character Elements” and “Cross-References” subsections to “Using the Chapter Elements.” Author James Cline James Cline

1.2.0 1.3.0 1.4.0

19 September 2002 11 October 2002 23 October 2002

James Cline James Cline James Cline

Contents

List of Illustrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .vii List of Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix Chapter 1: Working with the Training Manual Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1 Training Manual Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1 Books . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1 Chapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1 Guidelines for Chapter Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2 Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2 Lessons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3 Chapter Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4 Check Your Progress . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5 Using the Chapter Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5 Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5 Headings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5 Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6 Figures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-7 Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-8 Cautions, Notes, and Tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-8 Pull Quotes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-9 Cross-References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-9 Character Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-10 Creating the More Complex Chapter Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-10 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-10 Check Your Progress . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-10 Glossaries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-11 Treatment of Terms in Chapter Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-11 Treatment of Terms in the Glossary Section of a Book. . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-11 File Management and Naming Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-12 Setting Up a Project Folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-12 Backing Up Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-12 Naming Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-13 Handling Graphics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-13 Creating a New Training Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-14 Creating a File from a Template File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-15 Maintaining Formatting Consistency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-15 Document Versioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-15 Hints and Tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-16 Using List of References to Troubleshoot FrameMaker Issues. . . . . . . . . . . . . . . . . . . . . . 1-16

Training Manual Template Guide • v

Chapter 2: Sample Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-1 Heading1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2 Heading2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4 Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-1

vi • Training Manual Template Guide

Illustrations

Figure 1-1: Sample Figure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-7 Figure 2-1: Figure with Formats Called Out . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3

Training Manual Title • vii

Tables

Table 1-1: Field Descriptions Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-8 Table 2-1: Field Descriptions Table with Formats Called Out . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4

Training Manual Title • ix

Chapter 1:

Working with the Training Manual Template

Training Manual Structure
Books
The standard Memec training manual is organized into a FrameMaker book that comprises the following files in this order: • • • • • • • • • Title Page Copyright Page Revision History Table of Contents List of Illustrations List of Tables Chapters (as many as needed) Glossary (optional) Index (optional)

Chapters
Like books, chapters have a consistent structure with the following major sections: • • • • • • Chapter Title Introduction Objectives Lessons • Explanations of key concepts, tasks, and reference information • Exercises (optional) Chapter Summary Check Your Progress (optional)

Exercise and Check Your Progress sections are optional components and can be omitted when not appropriate for the content presented.

Guidelines for Chapter Sections
The following guidelines for the chapter sections should be observed to preserve the consistency of the training manuals. In the event that the following formatting elements do not work for the content you are

Chapter 1: Working with the Training Manual Template

developing, you should discuss this with the Template Designer so that the template can be revised and the changes incorporated into all manuals.

Introduction
Content and purpose. Use this section to introduce the subject and purpose of the chapter. The Introduction should be brief, consisting of about one to three short paragraphs. Stylistic conventions. This section contains no special stylistic conventions beyond those mentioned in the Training Style Guide (http://training.memec.com/resourcecenter/erp_guides/style_guide/WebHelp/ TrainingStyleGuide.htm). Elements used. The Introduction uses the following core elements:
Element Body Heading1NoTOC Type Paragraph Paragraph Used For body content the heading Introduction

Objectives
Content and purpose. A list of learning objectives follows the Introduction. These objectives can be conceptual, factual, or procedural in nature; in other words, they express what the learner will understand, know, or be able to do after completing the chapter. Stylistic conventions. The Objectives section begins with the statement: “After completing this chapter, you will be able to.” Avoid punctuating this statement with a colon. (Colons should only punctuate complete clauses in narrative text. In other words, a complete sentence should always precede a colon.) A list of learning objectives follows the lead-in statement. Each objective should be a verb phrase such as “Enter an order” that completes the introductory statement. Learning objectives should always express what the learner will be able to do after completing the training. See the Training Style Guide for more information on writing learning objectives. Elements used. The Objectives section uses the following core elements:
Element Heading1NoTOC Objectives Objectives1 Type Paragraph Paragraph Paragraph Used For the heading Objectives subsequent objectives first objective

1-2 • Training Manual Template Guide

Guidelines for Chapter Sections

Lessons
Content and purpose. The Lessons section is the instructional core of the chapter. The section is not explicitly labeled Lessons but includes all the content to teach a lesson: • • Explanations of key concepts, information, and tasks Exercises reinforcing the understanding of the explanations.

Stylistic conventions. This section contains no special stylistic conventions beyond those mentioned in the Training Style Guide (http://training.memec.com/resourcecenter/erp_guides/style_guide/WebHelp/ TrainingStyleGuide.htm). Elements used. Most of the elements in the various FrameMaker catalogs are used in the Lessons section.
Element Body Bulleted Bulleted1 Type Paragraph Paragraph Paragraph Used For Body text Subsequent items in a compact bulleted list The first item in a bulleted list. Can also be used for subsequent items if a loose format (additional space) is desired. Subsequent (or all) items in an indented bulleted list. This bullet hangs flush left with the text in a numbered list. The first item in an indented bulleted list if a line of space between the preceding text and the first bullet is required. This bullet hangs flush left with the text in a numbered list. Callout text used with figures The body cells of a FieldDescriptions table The second cell in an Exercise table. This format contains the numbered title of the exercise. The first cell in an Exercise table. This format creates the book icon The cells in the heading row of a FieldDescriptions table All cells in a DialogBoxOptions table

BulletedSub

Paragraph

BulletedSub1

Paragraph

Callout CellBody CellExercise

Paragraph Paragraph Paragraph

CellExerciseIcon CellHeading CellStepOption

Paragraph Paragraph Paragraph

Training Manual Template Guide • 1-3

Chapter 1: Working with the Training Manual Template

Element DialogBoxOptions

Type Table

Used For Tables showing the settings for various dialog box options. This table is designed to be used below the Numbered format. The numbered heading of an exercise. This table is anchored to the Exercise heading that introduces the Exercise section. Tables containing descriptions of software fields Graphics inserted as figures The caption of a figure All level 1 heads after the first level 1 head in the Lessons section. (The first level 1 head is Heading1NewPage.) First level 1 head in Lessons section (following Objectives) to force this head onto a new page. Level 2 heads Caution text. Note text. Tip text. All ordered list items such as steps All ordered list items subordinate to a higher-level numbered item The caption of a table Optional pull quotes

Exercise

Table

FieldDescriptions Figure FigureTitle Heading1

Table Table Paragraph Paragraph

Heading1NewPage

Paragraph

Heading2 NoteCaution NoteNote NoteTip Numbered NumberedSub TableTitle

Paragraph Paragraph Paragraph Paragraph Paragraph Paragraph Paragraph Paragraph

PullQuote

Chapter Summary
Content and purpose. The Chapter Summary—labeled simply Summary in the manual—provides the student with a recapitulation of the main points discussed in the chapter. The Chapter Summary should briefly restate what the student has just accomplished and then foreshadow what is coming next. Stylistic conventions. This section contains no special stylistic conventions beyond those mentioned in the Training Style Guide (http://training.memec.com/resourcecenter/erp_guides/style_guide/WebHelp/ TrainingStyleGuide.htm).

1-4 • Training Manual Template Guide

Using the Chapter Elements

Elements used. The Chapter Summary uses the following core elements:
Element Heading1NoTOC Body Type Paragraph Paragraph Used For The heading Summary The body text of the chapter summary

Check Your Progress
Content and purpose. The Check Your Progress section is an optional section used to let students evaluate their mastery of core concepts, procedures, and facts. This section consists of a series of multiple-choice or short-answer questions. Stylistic conventions. This section contains no special stylistic conventions beyond those mentioned in the Training Style Guide (http://training.memec.com/resourcecenter/erp_guides/style_guide/WebHelp/ TrainingStyleGuide.htm). Elements used. The Check Your Progress section uses the following core elements:
Element Type Used For The heading Check Your Progress Each question in the section The choices in a multiple-choice question

Heading1NoTOCCheck Paragraph Numbered NumberedSub Paragraph Paragraph

Using the Chapter Elements
Body
Use the Body paragraph tag for all body text.

Headings
Below the Chapter Title, there are three levels of headings: • • • Heading1 – Appears in TOC Heading2 – Appears in TOC HeadingRunIn – Does not appear in TOC

Training Manual Template Guide • 1-5

Chapter 1: Working with the Training Manual Template

Note
HeadingRunIn is typed as a separate paragraph but appears inline once you apply the format. In addition to these basic headings, there are also three other specialized headings that are equivalent to a Heading1 in format: • • • Heading1NoTOC – Used for the Introduction and Objectives heads, which are not listed in the table of contents. Heading1NewPage – Used for the first heading following the Objectives section. This heading appears on a new page. Heading1NoTOCCheck – Used for the Check Your Progress heading, which is prefixed with a symbol and also appears on a new page.

Lists
Bulleted Lists. Create a compact bulleted list using the following paragraph formats: • • • • • Bulleted1 Bulleted Bulleted Bulleted Bulleted

Create a loose bulleted list using just the Bulleted1 format: • • • • Bulleted1 Bulleted1 Bulleted1 Bulleted1

Advance organizers in lists of dense content. When your list items are long, it helps readers to scan and process the list more easily if you summarized each bulleted item with a term or phrase. This summarizing heading should be boldface (using the Strong character format) and then followed by a space, an en dash (Alt+0150), another space, and finally the text. The items in such lists are formatted using the Bulleted1 paragraph format, as in the following example: • Sed ut perspiciatis – unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam eaque ipsa, quae ab illo inventore veritatis et quasi architecto Beatae vitae dicta – sunt, explicabo. nemo enim ipsam voluptatem, quia voluptas sit, aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos, qui ratione voluptatem sequi nesciunt, neque porro quisquam est, qui dolorem ipsum,

1-6 • Training Manual Template Guide

Using the Chapter Elements

Quia dolor sit amet – consectetur, adipisci velit, sed quia non numquam eius modi tempora incidunt, ut labore et dolore magnam aliquam quaerat voluptatem. Ut enim ad minima veniam – quis nostrum exercitationem ullam corporis suscipit laboriosam, nisi ut aliquid ex ea commodi consequatur? quis autem vel eum iure reprehenderit, qui in ea voluptate velit esse, quam nihil molestiae consequatur, vel illum, qui dolorem eum fugiat, quo voluptas nulla pariatur?

Numbered Lists. Generally, numbered lists are used only in the Exercise and Check Your Progress sections. However, if you need to use a numbered list outside of those two sections, you can create the list using just the Numbered tag as follows: 1. Numbered a. NumberedSub

b. NumberedSub 2. Numbered a. NumberedSub

b. NumberedSub 3. Numbered

Figures
Note
Remember to import all graphics by reference. Figures are contained in a special Figure table that has one body cell for the figure with a table caption—Figure Title—below the table.
This is a callout

Figure 1-1: Sample Figure

Tip
To remove all space between a graphic and the anchored frame around it, select the frame and type Esc m p. You can position the figure by changing the width of the table cell: widening the cell pushes the figure to the left; narrowing the cell, to the center. Callouts are created by drawing a text frame and using the Callout paragraph format. Leader lines are solid black and 0.5pt wide. Be sure to draw the text box inside the anchored frame; otherwise, the text box and leader line will not move with the graphic.

Training Manual Template Guide • 1-7

Chapter 1: Working with the Training Manual Template

Figure captions should follow the guidelines for titles in headings described in the Training Style Guide.

Tables
There are two table formats: one for field descriptions and one for dialog box options. The FieldDescriptions table is used to describe the fields in a screen. Generally, it has two columns, one heading row, and no footing rows. Additional columns may be added if necessary (e.g., a “Modifiable” column).
Table 1-1: Field Descriptions Table Field Field 1 Field 2 Field 3 Field 4 Field 5 Description Description Description Description Description Description

The DialogBoxOptions table is used in procedures to describe the options in a dialog box. An example of the DialogBoxOptions table appears in step 3 in “Cautions, Notes, and Tips” on page 8. The DialogBoxOptions table has two columns and no heading or footing rows. Note also that it is anchored below a step. Table captions should follow the guidelines for titles in headings described in the Training Style Guide.

Cautions, Notes, and Tips
Cautions, notes, and tips provide important information that is supplementary to and departs from the topic under discussion. They are used as follows: • • • Cautions alert users to situations where equipment, data, or software may be damaged. (Warnings cover personal injury and so are currently not relevant to Memec’s training materials.) Notes can contain any content that is related but supplementary to the topic. Tips provide users with alternate, more efficient ways of doing something.

Notes, cautions, and tips are created simply by typing the required text and then applying the relevant paragraph format:

1-8 • Training Manual Template Guide

Using the Chapter Elements

• • •

NoteNote NoteCaution NoteTip

The note, caution, or tip appears in the side head area with an appropriate icon.

Pull Quotes
Pull quotes can be used wherever appropriate to provide context or inspiration for a chapter section. They are created within the PullQuote paragraph tag. After the quote, type Shift+Return twice to separate the quote from the attribution line. The attribution line should start with an en dash, created by typing Alt+0150 on your numeric keypad.
“In quo enim maxime consuevit iactare vestra se oratio, tua praesertim, qui studiose antiqua persequeris, claris et fortibus viris commemorandis eorumque factis non emolumento aliquo, sed ipsius honestatis decore laudandis” –Pull quote format. It can also be used within an anchored frame.

Cross-References
Section cross-references. For cross-references to other sections in a manual, use the Heading & Page cross-reference format preceded by the word See (or see if in the middle of a sentence). Example for a section cross-reference: See “Guidelines for Chapter Sections” on page 1 for more information. Table and figure cross-references. For references to tables and figures, use the Table Number and Figure Number cross-reference formats respectively. Examples for table and figure cross-references: Table 1-1 shows a sample Field Descriptions table. Figure 1-1 shows a sample figure.

Training Manual Template Guide • 1-9

Chapter 1: Working with the Training Manual Template

Character Elements
The following character formats are used throughout chapters:
Element Emphasis Strong Glossary Wingdings Type Character Character Character Character Used For Italics Boldface The first instance in a chapter of a term that appears in the Glossary The Autonumber format in paragraph formats with icons (e.g., NoteTip, Heading1NoTOCCheck, etc.)

Creating the More Complex Chapter Sections
Exercises
The Exercise section uses several of the above-mentioned formats. The following describes how to construct an Exercise section. The Exercise section starts with a normal Heading1 paragraph format. You then insert the Exercise table format, which is anchored to the heading. This format automatically numbers the exercise and inserts the book icon. The Exercise table is then followed by normal Numbered and NumberedSub paragraph formats. Use soft returns (Shift+Enter) to create hanging text below a numbered step for explanations or confirmations. To use a bulleted list within a step, use the BulletedSub1 and BulletedSub paragraph formats. In a step that has the learner fill in a number of dialog box options, you can use the DialogBoxOptions table format. For an example of using this table to show dialog box options within a procedure, see step 3 in “Cautions, Notes, and Tips” on page 8

Check Your Progress
You create the Check Your Progress sections as follows: 1. In a blank paragraph, type the heading Check Your Progress. 2. Apply the paragraph format Heading1NoTOCCheck to the heading. This format forces the heading to the top of the next page.

1-10 • Training Manual Template Guide

Glossaries

3. Press Enter to create the first question. 4. Use the NumberedSub paragraph formats for the answers to each question.

Glossaries
Most training manuals should have a glossary where special terms are defined. The glossary is a separate chapter that appears in the appendix section of a book.

Treatment of Terms in Chapter Text
The first use (in a chapter) of a term defined in the glossary should be set off in italics using the Glossary character format. The term should also link to the corresponding entry in the glossary. See “Inserting Links to Glossary Terms” on page 11 for instructions.

Treatment of Terms in the Glossary Section of a Book
Glossary entries consist of two structures: • • Term – Format the entry using the DefTerm paragraph format. Definition – Format the definition using the Body paragraph format.

If the definition contains a term that is also defined in the glossary, format it using the Glossary character format. To point the reader to another term in the Glossary, use the See Term cross-reference format.

Inserting Links to Glossary Terms
In chapters, link the first use of a glossary term to the corresponding entry in the glossary file. 1. Open the Glossary.fm file for your book if it is not already open. 2. In your chapter file, select the first occurrence of the term. 3. Choose Special > Cross-Reference. 4. In the Cross-Reference dialog box, do the following: a. From the Document list, choose Glossary.fm.

b. In Paragraph Tags, click DefTerm.

Training Manual Template Guide • 1-11

Chapter 1: Working with the Training Manual Template

c.

In Paragraphs, click the appropriate term.

d. From the Format list, choose First Use. e. Click Insert.

File Management and Naming Conventions
Setting Up a Project Folder
All files needed to develop and maintain a project should be kept in a project folder. This folder is to be located in our WIP workspace on the P drive (P:\Training\ERP Documentation\01_WiP). The project folder should be named so that it is easy for team members to identify the correct directory for a project without having to look inside. The project folder should consist of the following subfolders: • • • • • • Estimates and Tracking – Contains estimating and tracking spreadsheets and any other files used to manage the project Notes and Reference – Miscellaneous information, source documentation, or other notes Outlines – Inspiration outlines used in drafting your TOC or doing other prewriting activities Source – The actual source files of your project • Images – A subdirectory for all graphics Style Sheets and Standards – Style sheets (e.g., lists of words and their treatments) and other notes used to maintain stylistic consistency within your project z_Archive – A place to store files that are obsolete but perhaps not ready for permanent deletion

Backing Up Files
Although you will most likely copy a project folder to your PC to work on the project, you should update the project folder in the Training repository at least once a week. A good practice would be to update this directory at the end of the day every Friday. To create a clean update, delete the old project folder on P and then copy the folder on your PC to the repository on P. In addition to this weekly update of the Training repository, you should also backup your files every night to your home directory on the network (Z drive).

1-12 • Training Manual Template Guide

File Management and Naming Conventions

Naming Files
The FrameMaker files for your training manual book should be named and ordered as follows:

Note
The generated files—those ending in TOC, LOF, LOT, and IOM—are named automatically when you add them to your book. • • • • • • • • • Title.fm Copyright.fm Revisions.fm [book name]TOC.fm [book name]LOF.fm [book name]LOT.fm Chapter[x].fm Glossary.fm [book name]IOM.fm

In naming chapter files, you may find it helpful to add a descriptive word after the chapter number to label the content of the file, e.g., “Chapter1Intro.fm.”

Handling Graphics
In creating and adding graphics to your project, follow these guidelines: • • Keep all graphics—both original and final versions—in the Images subfolder of your Source folder. For every screen capture or other form of artwork, save at least two copies of the file: the final version saved in the native file format of the graphic application (e.g., .psp for PaintShop Pro) and the final version saved in the output format (e.g., .tiff or .wmf). You may also choose to save the original artwork before any image manipulation in the native file format of the application. If you opt for the latter (i.e., three files), name your files as follows: • • • • suffix the original source file with “_a” (e.g., “screen_capture_a.psp”) suffix the edited source file with “_b” (e.g., “screen_capture_b.psp”) suffix the output file simply with the target file format (e.g., “screen_capture.tif ”)

Use the following output file formats: • • TIFF for screen captures WMF for Visio files

Tip
Resize TIFFs by changing their resolution (DPI). Increase the DPI to reduce a graphic.

Import all graphics by reference.

Training Manual Template Guide • 1-13

Chapter 1: Working with the Training Manual Template

Creating a New Training Manual
1. Set up your project folder as described in “Setting Up a Project Folder” on page 12. 2. Copy the Source folder from the Training repository to your PC. The Source folder is located in the following network directory: P:\Training\ERP Documentation\Templates\FrameMaker Templates\Training Manual. 3. Rename the template book file (TrainingManual.book) appropriately for your project. 4. Open the book file in FrameMaker. 5. Open Title.fm and redefine the BookTitle variable in the Title.fm file. The BookTitle variable stores the title of your manual, controlling the title on the title page and on all footers. 6. Import the Variable Definitions from Title.fm into the remaining book files.

Tip
Import variable definitions by selecting all files but Title.fm in the book, choose File > Import > Formats, clear all check boxes except Variable Definitions, and then click Import. 7. In the Book window, rename Chapter.fm to Chapter1.fm and click OK at the confirmation messages. 8. Rename the four generated files—ending in TOC, LOF, LOT, and IOM—replacing TrainingManual with the same name you gave the book in step 3. Click OK at the confirmation messages. 9. In your Source folder, delete all the backup (e.g., TrainingManualTOC.backup.fm) files FrameMaker created when you renamed the generated files. 10. In the Book window, click Update Book and Generate Lists There should be no errors when you generate the book. 11. To begin writing, open Chapter1.fm and do one of the following: • Delete the sample text –or– • Leave the sample text there as a reference, pushing it down the page as you write above it. You can then delete the sample text later once you are familiar with all of the formats. .

1-14 • Training Manual Template Guide

Creating a File from a Template File

Creating a File from a Template File
When you need to add a second chapter to your book, create the new chapter file from the Chapter.fm template. 1. On the QuickAccess bar, click New Document .

2. Navigate to the Training Template folder, select the appropriate template file (e.g., Chapter.fm if you are creating a new chapter file), and click New. The Training FrameMaker templates are stored on the network at P:\Training\ERP Documentation\Templates\FrameMaker Templates\Training Manual\Source. 3. Save the file and add it to your book. 4. Reset the file’s Chapter and Page numbering properties. Except for the first chapter, which begins with chapter number 1, chapter numbers should continue from the previous file. Page numbers, on the other hand, should begin with 1.

Maintaining Formatting Consistency
To keep your project consistent with others in the Training library, follow these guidelines: • Do not change, add, or delete formats – If you need or want to change the template design, raise the issue at a team meeting. All changes need to be approved by the group and added to the template so that consistency across projects is preserved. Periodically reimport formats from the template – When the Template Designer announces a change to the template, reimporting the formats into the affected files. Also, before publishing a project, reimport all formats to ensure that you didn’t accidentally introduce any formatting overrides into your project.

Document Versioning
The Revision Number in the table on the Revisions page identifies a particular version of a document. For each version, indicate the revision number with three numbers as in the following example:

Training Manual Template Guide • 1-15

Chapter 1: Working with the Training Manual Template

1.1.0 • • • First number – Indicates a major release or redesign. The initial release of a document is indicated by 1. Increment this number only for a major release or redesign of the document. Second number – Indicates substantive changes to content or structure. Begin at 0 for the initial release and increment whenever you add, delete, or significantly change sections of the document. Third number – Indicates copyediting changes and minor corrections. Increment this number whenever the changes to a document are limited to small corrections that do not alter the content of the document.

Hints and Tips
Using List of References to Troubleshoot FrameMaker Issues
You can generate the following lists of elements referenced in a file: • • • • • • • Condition tags External cross-references Fonts Imported graphics Text insets Unresolved cross-references Unresolved text insets

The list is generated as a separate file. The list items can be clicked (Ctrl+Alt+Click) to jump to the referenced location in the source file. This can help you find, for example, the source of a missing font. 1. Choose Special > List Of > References. 2. Click Yes at the confirmation prompt. 3. In the Don’t Include list, double-click the item you want to build a list for. 4. Make sure that the Create Hypertext Links check box is selected.

1-16 • Training Manual Template Guide

ChapterTitle

Chapter 2:

Sample Chapter

Heading1NoTOC Body

Introduction
Sed ut perspiciatis, unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam eaque ipsa, quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt, explicabo. nemo enim ipsam voluptatem, quia voluptas sit, aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos, qui ratione voluptatem sequi nesciunt, neque porro quisquam est, qui dolorem ipsum.

Heading1NoTOC Body Objectives1 Objectives

Objectives
After completing this section, you will be able to Objective 1 Objective 2 Objective 3 Objective 4 Objective 5

Chapter 2: Sample Chapter

Heading1NewPage
Quia dolor sit, amet, consectetur, adipisci velit, sed quia non numquam eius modi tempora incidunt, ut labore et dolore magnam aliquam quaerat voluptatem. ut enim ad minima veniam, quis nostrum exercitationem ullam corporis suscipit laboriosam, nisi ut aliquid ex ea commodi consequatur? quis autem vel eum iure reprehenderit, qui in ea voluptate velit esse, quam nihil molestiae consequatur, vel illum, qui dolorem eum fugiat, quo voluptas nulla pariatur?

Heading1
Sed ut perspiciatis, unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam eaque ipsa, quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt, explicabo. nemo enim ipsam voluptatem, quia voluptas sit, aspernatur aut odit aut fugit.

Heading2
Ut enim ad minima veniam, quis nostrum exercitationem ullam corporis suscipit laboriosam, nisi ut aliquid ex ea commodi consequatur? quis autem vel eum iure reprehenderit, qui in ea voluptate velit esse, quam nihil molestiae consequatur, vel illum, qui dolorem eum fugiat, quo voluptas nulla pariatur? HeadingRunIn. In quo enim maxime consuevit iactare vestra se oratio, tua praesertim, qui studiose antiqua persequeris, claris et fortibus viris commemorandis eorumque factis non emolumento aliquo, sed ipsius honestatis decore laudandis, id totum evertitur eo delectu rerum, quem modo dixi, constituto.

Note
This is a note. Sicine eos censes aut in armatum hostem impetum fecisse aut in liberos atque in sanguinem suum tam crudelis fuisse, nihil ut de utilitatibus, nihil ut de commodis suis cogitarent? at id ne ferae quidem faciunt, ut ita ruant itaque turbent, ut earum motus et impetus quo pertineant non intellegamus, tu tam egregios viros censes tantas res gessisse sine causa? • • • • Bulleted1 Bulleted Bulleted Bulleted

Quae fuerit causa, mox videro; interea hoc tenebo, si ob aliquam causam ista, quae sine dubio praeclara sunt, fecerint, virtutem iis per se ipsam causam non fuisse. -- Torquem detraxit hosti. -- Et quidem se texit, ne interiret. -- At magnum periculum adiit. -- In oculis quidem exercitus. --

2-2 • Training Manual Template Guide

Heading1

Quid ex eo est consecutus? -- Laudem et caritatem, quae sunt vitae sine metu degendae praesidia firmissima. -- Filium morte multavit. -- Si sine causa, nollem me ab eo ortum, tam inportuno tamque crudeli; sin, ut dolore suo sanciret militaris imperii disciplinam exercitumque in gravissimo bello animadversionis metu contineret, saluti prospexit civium, qua intellegebat contineri suam. atque haec ratio late patet.

Caution
This is a caution. In quo enim maxime consuevit iactare vestra se oratio, tua praesertim, qui studiose antiqua persequeris, claris et fortibus viris commemorandis eorumque factis non emolumento aliquo, sed ipsius honestatis decore laudandis, id totum evertitur eo delectu rerum, quem modo dixi, constituto, ut aut voluptates omittantur maiorum voluptatum adipiscendarum causa aut dolores suscipiantur maiorum dolorum effugiendorum gratia. • Bulleted1 – At vero eos et accusamus et iusto odio dignissimos ducimus, qui blanditiis praesentium voluptatum deleniti atque corrupti, quos dolores et quas molestias excepturi sint, obcaecati cupiditate non provident, similique sunt in culpa, qui officia deserunt mollitia animi, id est laborum et dolorum fuga. Bulleted1 – At vero eos et accusamus et iusto odio dignissimos ducimus, qui blanditiis praesentium voluptatum deleniti atque corrupti, quos dolores et quas molestias excepturi sint, obcaecati cupiditate non provident, similique sunt in culpa, qui officia deserunt mollitia animi, id est laborum et dolorum fuga. Bulleted1 – At vero eos et accusamus et iusto odio dignissimos ducimus, qui blanditiis praesentium voluptatum deleniti atque corrupti, quos dolores et quas molestias excepturi sint, obcaecati cupiditate non provident, similique sunt in culpa, qui officia deserunt mollitia animi, id est laborum et dolorum fuga. Bulleted1 – At vero eos et accusamus et iusto odio dignissimos ducimus, qui blanditiis praesentium voluptatum deleniti atque corrupti, quos dolores et quas molestias excepturi sint, obcaecati cupiditate non provident, similique sunt in culpa, qui officia deserunt mollitia animi, id est laborum et dolorum fuga.
Callout

Tip
This is a tip.

FigureTitle

Figure 2-1: Figure with Formats Called Out

Et harum quidem rerum facilis est et expedita distinctio. nam libero tempore, cum soluta nobis est eligendi optio, cumque nihil impedit, quo minus id, quod maxime placeat, facere possimus, omnis voluptas assumenda est, omnis dolor repellendus. temporibus autem quibusdam

Training Manual Template Guide • 2-3

Chapter 2: Sample Chapter

et aut officiis debitis aut rerum necessitatibus saepe eveniet, ut et voluptates repudiandae sint et molestiae non recusandae. itaque earum rerum hic tenetur a sapiente delectus, ut aut reiciendis voluptatibus maiores alias consequatur aut perferendis doloribus asperiores repellat.
TableTitle CellHeading
Table 2-1: Field Descriptions Table with Formats Called Out Field Field 1 Field 2 Description Description Description Description Description Description

CellBody

Field 3 Field 4 Field 5

Quorum facta quem ad modum, quaeso, interpretaris? sicine eos censes aut in armatum hostem impetum fecisse aut in liberos atque in sanguinem suum tam crudelis fuisse, nihil ut de utilitatibus.
“Nihil ut de commodis suis cogitarent? at id ne ferae quidem faciunt, ut ita ruant itaque turbent, ut earum motus et impetus quo pertineant non intellegamus, tu tam egregios viros censes tantas res gessisse sine causa?” –Source

PullQuote

Heading1

Exercises
Exercise 1: Doing an exercise
1. Numbered a. NumberedSub
CellExercise

CellExerciseIcon

b. NumberedSub c. NumberedSub

2. Numbered • • • BulletedSub1 BulletedSub BulletedSub

2-4 • Training Manual Template Guide

Exercises

3. Numbered.
DialogBoxOptions table

Field Field Name:

Value Setting Setting Setting Setting Setting

CellStepOption

Field Name: Field Name: Field Name: Field Name:

4. Numbered.

Heading1NoTOC

Summary
Hanc ego cum teneam sententiam, quid est cur verear, ne ad eam non possim accommodare Torquatos nostros? quos tu paulo ante cum memoriter, tum etiam erga nos amice et benivole collegisti, nec me tamen laudandis maioribus meis corrupisti nec segniorem ad respondendum reddidisti.

Training Manual Template Guide • 2-5

Chapter 2: Sample Chapter

Heading1NoTOCCheck

Check Your Progress
1. Numbered. a. NumberedSub.

b. NumberedSub. c. NumberedSub.

d. NumberedSub. 2. Numbered. a. NumberedSub.

b. NumberedSub. c. NumberedSub.

d. NumberedSub. 3. Numbered. a. NumberedSub.

b. NumberedSub. c. NumberedSub.

d. NumberedSub.

2-6 • Training Manual Template Guide

Glossary

Glossary Term. Definition of the term. If the definition contains a term that is also defined in the Glossary, format it using the Glossary character format. To point the reader to another term in the Glossary, use the See Term cross-reference format. Test term. Sed ut perspiciatis, unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam eaque ipsa, quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt, explicabo. nemo enim ipsam voluptatem, quia voluptas sit, aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos, qui ratione voluptatem sequi nesciunt, neque porro quisquam est, qui dolorem ipsum, quia dolor sit, amet, consectetur, adipisci velit, sed quia non numquam eius modi tempora incidunt, ut labore et dolore magnam aliquam quaerat voluptatem. ut enim ad minima veniam, quis nostrum exercitationem ullam corporis suscipit laboriosam, nisi ut aliquid ex ea commodi consequatur? quis autem vel eum iure reprehenderit, qui in ea voluptate velit esse, quam nihil molestiae consequatur, vel illum, qui dolorem eum fugiat, quo voluptas nulla pariatur? Glossary Term.

Index

B
body text 1-5 books creating 1-14 structure of 1-1

I
Introduction section 1-2

L
leader lines 1-7 Lessons section 1-3 lists 1-6

C
callouts 1-7 captions figures 1-8 tables 1-8 cautions 1-8 Chapter Summary section 1-4 chapters creating 1-15 structure of 1-1 character elements 1-10 Check Your Progress section 1-5, 1-10 cross-references 1-9

N
naming conventions for files 1-13 notes 1-8

O
Objectives section 1-2

P
project folders 1-12 pull quotes 1-9

E
Exercises section 1-10

F
figures 1-7 files creating from the template 1-15 managing 1-12 naming conventions for 1-13

R
Revisions page 1-15

T
tables 1-8 template location of files 1-14 process for changing 1-1, 1-15 tips for readers 1-8 for working with FrameMaker 1-16 training manuals, creating 1-14

G
glossaries 1-11 graphics 1-13

H
headings 1-5 hints 1-16

V
version numbers 1-15

Sign up to vote on this title
UsefulNot useful