Procedure Style Guide

8/13/2019 Procedure Style Guide

1/60

Procedure Style Guide

Oracle Tutor R14

October 2010


2/60

Copyright 1994 - 2010, Oracle. All rights reserved.

License Restrictions & Warranty DisclaimerThe Programs (which include both the software and documentation) contain proprietary information; they are provided under alicense agreement containing restrictions on use and disclosure and are also protected by copyright, patent, and other intellectualand industrial property laws. Reverse engineering, disassembly, or decompilation of the Programs, except to the extent required toobtain interoperability with other independently created software or as specified by law, is prohibited.

The information contained in this document is subject to change without notice. If you find any problems in the documentation,please report them to us in writing. This document is not warranted to be error-free. Except as may be expressly permitted in yourlicense agreement for these Programs, no part of these Programs may be reproduced or transmitted in any form or by any means,electronic or mechanical, for any purpose.

Restricted Rights NoticeIf the Programs are delivered to the United States Government or anyone licensing or using the Programs on behalf of the UnitedStates Government, the following notice is applicable:

U.S. GOVERNMENT RIGHTSPrograms, software, databases, and related documentation and technical data delivered to U.S. Government customers are"commercial computer software" or "commercial technical data" pursuant to the applicable Federal Acquisition Regulation andagency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the Programs,including documentation and technical data, shall be subject to the licensing restrictions set forth in the applicable Oracle licenseagreement, and, to the extent applicable, the additional rights set forth in FAR 52.227-19, Commercial Computer Software--

Restricted Rights (June 1987). Oracle USA, Inc., 500 Oracle Parkway, Redwood City, CA 94065.

Hazardous Applications NoticeThe Programs are not intended for use in any nuclear, aviation, mass transit, medical, or other inherently dangerous applications. Itshall be the licensee's responsibility to take all appropriate fail-safe, backup, redundancy and other measures to ensure the safe useof such applications if the Programs are used for such purposes, and we disclaim liability for any damages caused by such use ofthe Programs.

Third Party Web Sites, Content, Products, and Services DisclaimerThe Programs may provide links to Web sites and access to content, products, and services from third parties. Oracle is notresponsible for the availability of, or any content provided on, third-party Web sites. You bear all risks associated with the use ofsuch content. If you choose to purchase any products or services from a third party, the relationship is directly between you and thethird party. Oracle is not responsible for: (a) the quality of third-party products or services; or (b) fulfilling any of the terms of theagreement with the third party, including delivery of products or services and warranty obligations related to purchased products orservices. Oracle is not responsible for any loss or damage of any sort that you may incur from dealing with any third party.

Trademark NoticeOracle is a registered trademark of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respectiveowners.

Author

Emily Chorba

Technical Contributors and Reviewers

Mary Keane, Tom Kauth, Stuart Dunsmore, Chuck Jones

This book was published using: oracletu tor


3/60

Copyright Oracle, 2010. All rights reserved.

Student Guide Table of Contents

i

Table of Contents

Procedure Style Guide [EDU007PD_2010SEP] ..............................................................................................1-1

Introduction - How to use this guide ...............................................................................................................1-3

Developing a Procedure .................................................................................................................................1-4

Procedure Composition ..................................................................................................................................1-7

Introductory Segment .....................................................................................................................................1-8Introductory Segment: Scope .........................................................................................................................1-9

Introductory Segment: Policy .........................................................................................................................1-10

Introductory Segment: Responsibility .............................................................................................................1-11

Introductory Segment: Distribution (REQUIRED) ...........................................................................................1-12

Introductory Segment: Ownership (REQUIRED)............................................................................................1-13

Task Segment ................................................................................................................................................1-14

Task Segment: Activity Preface .....................................................................................................................1-15

Task Segment: Activity Preface (Trigger information) ....................................................................................1-16

Task Segment: Activity Preface (Generic Actor information) .........................................................................1-17

Task Segment: Activity Preface (Prior Activity information) ...........................................................................1-19

Task Segment: The Actor Bar ........................................................................................................................1-20Task Segment: Primary Tasks (Task 1) .........................................................................................................1-21

Task Segment: Directives ..............................................................................................................................1-23

Task Segment: Conditional Directives ...........................................................................................................1-25

Task Segment: Unconditional Directives ........................................................................................................1-28

Task Segment: Parallel Directive ...................................................................................................................1-30

Task Segment: Secondary Tasks or Steps (Task 2) ......................................................................................1-33

Task Segment: Qualifiers ...............................................................................................................................1-34

Task Segment: Note and Note List ................................................................................................................1-36

Task Segment: System References (Box Text) .............................................................................................1-37

External References .......................................................................................................................................1-39

Job Title Syntax ..............................................................................................................................................1-41

Miscellaneous Style Standards ......................................................................................................................1-42

Capitalization..................................................................................................................................................1-43

Examples of Conditional Directives ................................................................................................................1-44

Sample Directives Example 1 ........................................................................................................................1-45




Terms and Usage ...........................................................................................................................................1-50

Word Use .......................................................................................................................................................1-51


4/60


5/60



iii

Documentation Accessibility

Our goal is to make Oracle products, services, and supporting documentation accessible, withgood usability, to the disabled community. To that end, our documentation includes features thatmake information available to users of assistive technology. This documentation is available inHTML format, and contains markup to facilitate access by the disabled community. Standardswill continue to evolve over time, and Oracle Corporation is actively engaged with other market-

leading technology vendors to address technical obstacles so that our documentation can beaccessible to all of our customers. For additional information, visit the Oracle AccessibilityProgram Web site at http://www.oracle.com/accessibility/.

This documentation may contain links to Web sites of other companies or organizations thatOracle Corporation does not own or control. Oracle Corporation neither evaluates nor makesany representations regarding the accessibility of these Web sites.


6/60



iv

Send Us Your Comments

OracleTutor

Oracle welcomes your comments and suggestions on the quality and usefulness of thispublication. Your input is an important part of the information used for revision.

Did you find any errors?

Is the information clearly presented?

Do you need more information? If so, where?

Are the examples correct? Do you need more examples?

What features did you like most about this manual?

If you find any errors or have any other suggestions for improvement, please indicate themanual, chapter, section, and page number (if available). You can send comments to us via E-mail to [email protected]

If you would like a reply, please provide your name, company or organization that owns theTutor license, address, email, and telephone number with your correspondence.

If you have problems with the software, please contact your local Oracle Support Services or loga support request on line using your Customer ID at support.oracle.com.


7/60

Copyright 2010, Oracle and/or its affiliates. All rights reserved.

Introduction - How to use this guide

Chapter 1 - Page 1

Procedure Style Guide

Chapter 1


8/60



Chapter 1 - Page 2


9/60



Chapter 1 - Page 3


This style guide comprises the specific rules, or standards, that are followed in the developmentand modification of Tutor procedures. It provides standards that ensure continuity in

Writing style

Design/format

Syntax

Procedure-writing methodology

This guide expands on the information provided in the various Tutor document-writinginstructions, and it can be used as a reference tool or it can be used as a training tool for newDocument Administrators or Document Specialists.

To facilitate the use of this style guide as a reference tool, there is an index which cross-references style rules by topic. The index is especially useful when trying to answer a specificstyle question.

To facilitate the use of this style guide as a training tool, it is organized into sections thatcorrespond to the sections in a procedure. It gives the writer a sense of how procedures are"built."

Because this style guide addresses a unique process (i.e., writing procedures that conform toTutors style), terminology unique to Tutor has been used throughout this guide. Please refer tothe "Tutor Glossary of Terms" in the TutorAuthor User Manualand Tutor ImplementationGuide. Additionally, terminology specific to publishing appears in some of the format rules. Tutorsuggests, therefore, that you read the Terms and Usage section of this manual first.

For the Experienced Editor and Technical Writer

In the course of editing standard Tutor procedures, you may work with style standards thatseem arbitrary, or you may want to change an existing style. This Style Guide attempts toexplain a standard, and sometimes, why it was adopted.

Note: Altering a Tutor style may impact Tutor software functions.

It would be impossible for us to test all the possible variations that our world of Tutor users canthink of. The software tools were developed to work with a specific set of standards, and thosehave been carefully tested and verified.

If you wish to change a style, please test if fully with EVERY feature of the software tools beforemaking a document-wide change.


10/60


Developing a Procedure

Chapter 1 - Page 4


In order to use Author to write a procedure, you will need to understand the characteristics of aTutor procedure.

A procedure is:

The complete documentation of an activity, including the policies governing the activity

The tasks performed in the completion of the activity, and the people (by job title) whoperform those tasks

An activity is documented via a procedure if

standardization of the activity is possible

consistent performance is critical

there is a clear sequence of tasks

specific job roles must perform specific tasks in a coordinated effort

Not all critical activities lend themselves to procedures. For example, there is no standardsequence of tasks for "developing new product ideas." Similarly, not all easily-documentedactivities require procedures because, in many cases, consistent performance is not an

issue.

What Does the Procedure Writer Need to Know?

To write an effective procedure, you must understand:

The details of the activity that you are documenting (who, what, and when)

How the activity is integrated with other activities

The sequence of eventsthe beginning point, the ending point, and tasks that aredependent on other tasks

The job roles who perform the specific tasks

Job Titles or Roles

Procedures are a documented plan for how people in an organization proceed to do theirindividual jobs. Therefore, it is important to define the roles of the team members consistently.Company employees in Tutor procedures are referred to by their job title or job role.

The consistent use of job titles/roles is extremely important to many of the features in Tutor. Toenjoy the automation features of Tutor software, specific job title/role syntax must be followedwhen defining which job roles perform which tasks in the procedures.

Please see the section on Job Title syntax for explicit details on defining job titles/roles properly.

Other characteristics about procedures

An activity is covered by one (and only one) procedure.

Each procedure title must be unique.

A procedure must describe an activity; a procedure should not be used to describe a singletask.

For example, "shipping" may be defined as an activity; it is documented, therefore, via aprocedure. None of the tasks within that activity, however, should be documented as aseparate procedure. If "labeling cartons" is part of the shipping activity, it should bedocumented as a task within that procedure. If several steps are required to "label cartons,"those steps should be described below the task. Alternatively, the steps may be listed in aseparate support document (instruction) that is referenced under the task.


11/60



Chapter 1 - Page 5

Procedure titles should be limited to (approximately) 50 to 60 characters to avoid wrapping inthe footer where the document title appears at the bottom of every printed page.

The limit is approximate because Tutor procedures use proportional fonts.

Each procedure has a single effective date.

A documents effective date should be temporarily replaced with a draft level (or revisionlevel) during the edit phase. Once approved, the draft level should be replaced with a new

effective date.

Tutor procedure layout and format

A key activity companies must complete prior to documenting business practices is to agree onan appropriate writing system and manual structure. Some favor Leslie Matthies' Playscript;others prefer Robert Horn's Information Mapping or Structured Writing. Still others prefer to usea combination of tools, styles, and layouts.

Tutor Developers believe that the Playscript technique, developed by Leslie H. Matthies, is stillone of the best methods for documenting procedural activity. Its main advantages are:

it easily establishes and clarifies responsibility

it is an excellent tool for getting agreement

it simplifies writing it forces brevity

it provides for easy handling of non-routine procedures

it simplifies the introduction of change

it provides a uniform format

it is an excellent training tool

it can be used in any organization

it is suitable for on-line documentation

The Tutor procedure writing method, software tools, cross reference reports, and role basedprocess documentation desk manuals are based on the Playscript procedure writing style.

Other types of documents, however, augment the information contained in procedures. Tutorextends some of the Playscripts design elements to other business document types andprovides an organization with policies, procedures and support documents that have a uniformlook and feel. The other types of process documents included in the Tutor system are:

Business form A document used to record and track dynamic datarequired to complete a task or activity

Coding convention A document describing the rules governing how aspecific code or numeric identifier is formatted,assigned, controlled, and used

Instruction A detailed description of how to complete a specific task

in an activity; similar to a procedure, but involving asingle performer

Reference document A document used to convey guidelines or parametersrequired to complete a task or activity; includesspecifications, checklists, tables, charts, etc.

Each of these documents provides different information, but the intent of all documents is thesame: to support the successful completion of activities.

In the Tutor environment:


12/60



Chapter 1 - Page 6

The procedure focuses on the tasks required to complete an activity. Instructions,forms, coding conventions, and reference documents focus on a specific task within anactivity.

A procedure may include references to other types of process documents (such asforms or instructions) that are used to complete tasks within the activity. The procedureclarifies when and how these documents are used.

An activity may be supported by any combination of documents: a procedure alone, aprocedure and support documents, or by support documents alone. For example, ifonly one task in an activity is complex, that activity may be supported by an instructiononly (and no procedure).

Keep the layout simple

The formatting and layout of Tutor documents is simple on purpose. If updating documentsbecomes an exercise in complex formatting, then documents will not be kept up to date.

Another feature of the Tutor format and layout is that the resulting documents are compliant withthe American Disabilities Act (ADA).

Procedure File Names

Tutor documents reflect an eight-character alphanumeric filename composed of two letters(indicating document type) and a non-significant, six character alphanumeric identifier. Forexample: ??######

?? = document type (PR for procedures)

###### = unique alphanumeric identifier

A filename may not contain the following characters / \ : * ? " < > |

For procedures, Tutor uses PROfor the first three characters of the file name.


13/60


Procedure Composition

Chapter 1 - Page 7

Procedure Composition

Each procedure contains required segments and sections in the following sequence:

One Introductory segment

Scope: Describes what the procedure covers and what it does not cover.

Policy: Lists all of the rules that directly affect the activity

Responsibility: Identifies primary duties for each person who performs tasks in theactivity

Distribution: Lists each person who needs to receive a copy of the procedure

Ownership: Identifies the person responsible for ensuring the procedures integrity andaccuracy

One Task segment

Activity Preface: Identifies the starting point (the trigger or catalyst) of the activity

Tasks: Lists all of the tasks required to complete the activity

One Flowchart segment

Flowchart: A graphic representation of the activity at the task level


14/60


Introductory Segment

Chapter 1 - Page 8

Introductory Segment

A procedure must have an introductory segment, comprising these sections in the followingsequence:

Scope

Policy

Responsibility

Distribution

Ownership

References to external procedures must include the complete procedure title and the procedurefile name.

This procedure does not cover updating procedure documents. Refer to Document Update[INSxxxxx]

All of the introductory statements are written in present tense. In other words, policy statementsshould not be written in future tense.

The introductory segment is formatted using the Tutor Author template. The following paragraphstyles are used:

Text Type Allowed Paragraph Style

Headings Section Title

Scope statement Body Text, List Bullet

Policy statement Body Text, List Bullet, Note List 1

Responsibility statement Body Text, List Bullet

Distribution Body Text

Ownership statement Body Text

Only use the allowed paragraph styles in the Introduction section.


15/60


Introductory Segment: Scope

Chapter 1 - Page 9

Introductory Segment: Scope

The Scope section defines the activity that is covered by the procedure. It is most often anexpansion of the procedure title.

Scope

This procedure covers closing the general ledger for a single division or site.This procedure does not cover the close of consolidated general ledgers. Thisprocedure does not cover the overall monitoring of the close and the activitiesthat may be required to avoid delays in closing the general ledger. Refer toMonitoring the Close and Avoiding Delays [PROxxxxx].

Example 1: Scope Statement

If the activity is likely to be confused with other related activities, the Scope section mayalso identify those activities that are NOT covered.

References to external procedures should be included in the Scope section whenever suchreferences help direct the user to the correct procedure. Please refer to the section on ExternalReferences for correct syntax.

Scope

This procedure covers ...

This procedure does not cover ...

Example 2: The Scope section must conform to standard wording


16/60


Introductory Segment: Policy

Chapter 1 - Page 10

Introductory Segment: Policy

The Policy section comprises individual policy statements that relate to the activity.

A policy statement

focuses on a single topic, but it may define multiple facets of that topic

does not include explanation or justification

does not define how the policy will be implemented or enforced

Policy

Every customer ordermust be invoiced within one working day of shipment.

Standard freight chargesare

calculated based on a freight rate table

included as a line item on the customer order (that is, as a specialcharge)

estimated and do not reflect actual freight costs, unless the customerspecifies the carrier or mode of transportation

Example 3: Policy Statement

Every policy statement has an "owner," i.e., a person who has the authority to alter or revoke it.

At this time, the policy owners are not identified in the procedure.

Policy statements are written in the present tense.

Tutor Software Requirement

The Policy heading must be formatted with the Section Title paragraph style.

The main subject of a policy statement is formatted in bold.

The policy subject may only span one continuous string of bold text.

The statements must be formatted with the Body Text paragraph style.

Bulleted items must be formatted with the List Bullet paragraph style.


17/60


Introductory Segment: Responsibility

Chapter 1 - Page 11

Introductory Segment: Responsibility

The Responsibility section comprises individual responsibility statements, each related to aspecific job title.

A responsibility statement

represents a portion of an employees complete job description

defines those duties that relate to that specific job title in that specific procedure

describes duties at a high level, rather than at a task level

Responsibility statements

may only specify a singular job title, even if multiple employees share that job title

are written in the present tense

are written in parallel form using verbs ending in ing

The Responsibility section may include employees who do not participate in the activity

Responsibility

The Accounts Receivable Supervisor is responsible for

maintaining appropriate audit trails

verifying that all sales orders have been invoiced

approving requests for miscellaneous invoices

Example 4: Responsibility Statement


The Responsibility heading must be formatted with the Section Title paragraph style.

Responsibility statements must conform to standard wording

The is responsible for

Not acceptable

The are responsible for

A is responsible for

are responsible for

The standard responsibility string must be formatted with the Body Text paragraphstyle

Bulleted items must be formatted with the List Bullet paragraph style

Guideline: ratio of responsibility statements to tasks for each actor

Ratio = 1 to 6. That is, if an actor has 6 tasks in a procedure, there should be a single

responsibility statement for that actor. The responsibility section is a SUMMARY ofwhat an actor does in the task segment. DO NOT restate each task in the responsibilitystatements.


18/60


Introductory Segment: Distribution (REQUIRED)

Chapter 1 - Page 12

Introductory Segment: Distribution (REQUIRED)

The Distribution section is the section to list the job titles of those who should receive thedocument.

At a minimum, the actors for this specific activity must be listed.

The Distribution section may include employees who do not participate in the activity.

Please refer to the Job Title Syntax section in this document to ensure accurate job titleentries in the Distribution.

Distribution

Buyer*

Production Control Planner*

Purchasing Manager*

Vice President of Operations

Example 5: Distribution section

This section can be automatically populated with a feature in Author.An asterisk(*) after the job title means the job title is added by the Author Update Distributionfeature.

NO asterisk(*) means the job title is added manually.


This section is required - do not delete this section from any Tutor document

The Distribution heading must be formatted with the Section Title paragraph style.

Job titles listed under the Distribution heading must be formatted with the Body Textparagraph style.


19/60


Introductory Segment: Ownership (REQUIRED)

Chapter 1 - Page 13

Introductory Segment: Ownership (REQUIRED)

The Ownership section defines the person (by job title) who is responsible for ensuring that theprocedure (or document) is necessary and that it reflects actual practice, and that it conforms tocorporate policy.

An owner is often the manager who is one level above the principal performer in aprocedure. An owner, however, need not be a manager.

A procedure can have only ONE owner.Ownership statements are written in the present tense.

Ownership

The [Job Title] is responsible for ensuring that this document is necessary andthat it reflects actual practice.

Example 6: Ownership statement


This section is required - do not delete this section from any Tutor document

The Ownership heading must by formatted with the Section Title paragraph style.

The ownership statement must be formatted with the Body Text paragraph style.

The ownership statement must conform to standard wording.

The is responsible for

Not acceptable

The are responsible forA is responsible for are responsible for


20/60


Task Segment

Chapter 1 - Page 14

Task Segment

Each task segment comprises an Activity Preface, Actors, and related tasks.

All tasks required to complete an activity are listed, even if those tasks involve persons indifferent departments.

Task segments are written using playscript format. Playscript format is the preferred methodfor documenting procedures that require more than one actor to complete a single activity. It

uses a format where you designate the actor or job role responsible and then list the tasks theyare required to complete in the sequence in which they should be performed.

Task segments are formatted using the styles in Author.dot. The following styles used are:

Procedure Text Author.dot Template Style

Activity Preface heading Section Title, initial caps

Preface text Body Text

Preface indented text List Bullet

Actor job title or role Actor Bar

Task - primary Task 1

Primary task notes Note 1

Listing under a primary task Note List 1

Task - secondary Task 2

Secondary task notes Note 2

Listing under a secondary task Note List 2

Directives Directive

Qualifiers Qualifier

System references Box Text

Table information Table

Table Heading Table Header


Each paragraph must be associated with a valid Author.dot style.

Tasks are numbered sequentially, regardless of the branching within the task segment.


21/60


Task Segment: Activity Preface

Chapter 1 - Page 15

Task Segment: Activity Preface

Each task segment begins with an Activity Preface that:

defines when an activity is performed and whether it is routine or reactive

describes any restrictions that might apply

defines generic job titles (as needed)

includes any other information that might be useful to the reader

Activity Preface

This activity is performed each period and is initiated on the dates specified in theStandard Journal Entry Log [FOR0659Y].

The Close Schedule shows the relationship of adjustments to the overall plan forclosing the general ledger.

The job title Recipient refers to one of the following:

Accounts Payable Supervisor

Accounts Receivable Supervisor

Controller

Cost Accounting Manager

General Accounting Manager

Prior Activity

Processing Subledger Data to the General Ledger [PRO1114Y]

Example 7: Activity Preface section


The title Activity Preface must be formatted using the Section Title style.

Preface text is formatted using Body Text and the List Bullet style.

Generic job title string: The job title refers to


22/60


Task Segment: Activity Preface (Trigger information)

Chapter 1 - Page 16

Task Segment: Activity Preface (Trigger information)

The first part of the Activity Preface is used to describe the trigger, or the circumstance, thatinitiates this activity.

Begin your statement with: This activity is performed

Usually the Activity Preface begins with: This activity is performed when or Thisactivity is performed in response to

If the activity is performed routinely, then say so. For example , This activity isperformed on the first day of each month.

Focus on the catalyst (or the timing) of the activity, rather than on the scope of theactivity.

The first paragraph of the Activity Preface is one sentence in length and follows standardwording.

Activity Preface

This activity is performed [frequency] OR

This activity is initiated by [what or whom] ORThis activity is performed when [condition]

Example 8: Wording of Activity Preface trigger statement


23/60


Task Segment: Activity Preface (Generic Actor information)

Chapter 1 - Page 17


A generic job title (such as Originator) may be used as an actor when a task is associated withthree or more job titles.

When a generic actor is used, its equivalent job titles must be defined in the Activity Prefaceusing a feature called the generic job title string.

The definition of a generic job title (the generic job title string) must conform to standard wording

and format.


The generic job title string is formatted with the Body Text style (for the lead line)

The exact words The job title refers to must be used

The job titles are formatted with the List Bullet Style

Correct job title syntax must be used when listing the job roles

Please refer to the section on Job Tit le Syntaxin this document to ensure accurate jobtitle entries under the generic job title string.

The job title Originator refers to any of following: generic job title string Buyer

Facilities Manager

Production Control Planner

Example 9: Generic Job title string in the Activity Preface

When defining generic job titles, you may distinguish between a generic job title that equates tomultiple job titles simultaneously and a generic job title that equates to only one job title at atime.

The job title Requester refers to oneof the following:

Vice President of Finance

Director of Quality

Purchasing Manager

Example 10: The title Requester equates to any one of the titles on the list, but only one title is valid at any

given time.

The job title Reviewer refers to allof the following:

Vice President of Finance

Directory of Quality

General Accounting Manager

Example 11: The title Reviewer equates to all of the job titles listed, because all of those individuals are

"reviewers" simultaneously.

When two actors can perform a task in a procedure, do not use a generic job title. Simply enterboth job titles in the Actor bar using the standard job title separator syntax. Please refer to the


24/60



Chapter 1 - Page 18

section on Job Title Syntaxin this document to ensure accurate multiple job title entries in anactor bar.


25/60


Task Segment: Activity Preface (Prior Activity information)

Chapter 1 - Page 19

Task Segment: Activity Preface (Prior Activity information)

The Prior Activity statement lists any preceding procedure that directly initiatesthe action inthe task segment.

Activity Preface

This activity is initiated by receipt of a check request.Prior Activity

Accounts Payable Mail Processing [PRO1004Y]

Entering Recurring Invoices [PRO1011Y]

Sales Commission Processing [PRO1086Y]

Example 12: Prior Activity listing in the Activity Preface

Procedure references occurring under the heading Prior Activityshould follow standardformatting in the body text style:

Procedure Title [FileName]

Entering Recurring Invoices [PRO1011Y]


The Prior Activity heading must be used if you wish the prior activity references toshow up in the flowchart.

The Prior Activity heading must be formatted with the Subheador Section TitleParagraph style.

List each document title and file ID on a separate line formatted with the Body Textparagraph style.


26/60


Task Segment: The Actor Bar

Chapter 1 - Page 20

Task Segment: The Actor Bar

An actor bar separates the Activity Preface information from the tasks.

Any information that logically precedes task #1 should be included in the Preface.

Accounts Payable Clerk

1. Verify that required signatures are present on the check request.

Example 13: The Actor Bar must be followed by a Task 1 paragraph; it may not be followed by a directive or

note paragraph style

The actor bar paragraph style

shows up on the flowchart

appears as a shaded bar

should only contain the job title(s) of the individual(s) who are to perform the numberedtasks that follow

should only contain one to three job titles

Note: use a generic job title reference for more than three job titles that can perform thesame series of tasks.

Job titles/roles in the Actor Bar must adhere to the Tutor Job Title Syntax

Please refer to the section on Job Tit le Syntaxto ensure accurate use of job titles in theActor Bar.


27/60


Task Segment: Primary Tasks (Task 1)

Chapter 1 - Page 21


Writing Guidelines and Rules

Each task in the action section represents a separate and distinct action that is required in thecompletion of the activity.

Each task must begin with the verb. The initial verb in a task describes the primary action, or

purpose, of the task.

To determine the primary action of the task, focus on whatthe task accomplishes, rather thanhow or why it is done.

Procedures are much more effective when the individual tasks convey purpose, rather thanmethod.

Tasks are stated in the present tense.

Each task is associated with an actor, i.e., the job title responsible for completing the task.

Stockroom Clerk

22. Updates inventory.

Example 14: Task 1 paragraph style associated with an Actor

The actor is implied (i.e., not explicitly stated) if the previous task is performed by the sameactor.

Actors are identified by specific job title or by generic job title.

A generic job title may be used when a task or series of tasks are performed by multiple actors.

Generic job titles include Requester, Reviewer, Originator, and Recipient.

Tasks should not include references to specific computer system files or records.

Words within tasks should not be emphasized.

The wording of a task should be clear and succinct; if emphasis is required, it is usuallybetter to rewrite the task.


28/60



Chapter 1 - Page 22

In the following examples, two versions of the same task are shown; the first focuses on what;the second focuses on how.

Stockroom Clerk

23. Updates inventory.

Example 15: Recommended writing style, communicates 'what'

Stockroom Clerk

23. Accesses the computer system to update inventory.

Example 16: Not recommended, communicates 'how'


The Task 1 style must only be used in the task segment - DO NOT use in the

Introduction Segment.

The Task 1 style must begin with a number, followed by a period, followed by a tab.

Task 1 paragraphs appear on flowcharts in the task block.


29/60


Task Segment: Directives

Chapter 1 - Page 23


It is critical that directives in Tutor documents are written correctly as the flowchart feature ofTutor Author is extremely dependent on correct syntax and formatting of directives wheninterpreting your document.

Tutor supports the following directives: conditional, unconditional, and parallel

Directives are used to accommodate the variations in task sequences that naturally occur in the

performance of an activity.Directives appear between numbered (primary) tasks only.

Directives appear in bold.

The Author.dot template automatically formats directives in bold.

The following are valid directive phrases:

goto

stop and complete

end of activity


Directive statements must conform to the required syntax.

Directive statements must be formatted with the Directive paragraph style.

Directive statements show up on the flowcharts.

Gotois used to point to another task or procedure.

24. Files the inventory document.

If the material is a rush shipment, goto task #25. Otherwise, goto task #30.

Example 17: Both goto directive statements point to a task.

24. Files the inventory document.

If the material is not a rush shipment, end of activity; gotoCycle Count ing[PROxxxxx]. Otherwise, goto task #25.

Example 18: One of the goto directive statements points to a procedure


30/60



Chapter 1 - Page 24

Stop and completeis used to indicate an external procedure that interrupts the normal flow oftasks -- that is, a procedure that must be completed BEFORE the user proceeds with the nexttask.

4. Verify that an item master file exists for each item.

If item master files exist for all items, goto task #5. Otherwise, stop andcomplete Processing an I tem A ddi t ion/Delet ion [PROxxxxx ].

5. Update the

Example 19: The stop-and-complete directive instructs the user to complete PROxxxxx and then continue

with task #5.

A stop-and-complete directive can only reference a procedure; it cannot specify a task.

End of activityindicates that all the required tasks for that activity have been completed.

Since a task segment may have several distinct branches of activity, it may also have more thanone end of activitydirective.

7. Returns the PR to the Requester.

End of activity.

8. Returns the PR to the Material Control Coordinator.

End of activity.

Example 20: Multiple End of activity directives may be necessary.

Directives do not have an implied "performer." That is, directives MUST NOT be associated withjob titles.

Stockroom Clerk: Stop and complete Issuing Material [PRO0220Y].

Example 21: Do not associate directives with an actor or job title.


31/60


Task Segment: Conditional Directives

Chapter 1 - Page 25


A conditional directive identifies two or more mutually exclusive paths within an activity, only oneof which can be valid at any given time. An unconditional directive specifies a single jump orpath.

1. Update inventory.

If issuing the material to WIP, goto task #2. Otherwise, goto task #3.

2. Attach the Material Requisition to the production material.

Goto task #25.

3. Inform the Requester

Example 22: Conditional and unconditional directive

Conditional directives begin with the word If.

A conditional directive can never stand alone. (That is, there must at least two conditionaldirectives.)

When writing conditional directives, use the word otherwiseto express the second (or final)

condition.

14. Reviews the form for accuracy.

If the form is accurate, goto task #16. Otherwise, goto task #15.

15. Returns the form to the Requester.

Example 23: Conditional directive

Whenever a directive is used, the next task in the sequence is assumed to be inappropriate. Ifthe next task in sequence isappropriate (perhaps under some condition), a second directivemust point to it.

3. Completes a Credit Analysis form.

If the request is from an existing customer, goto task #5. Otherwise, gototask #4.

4. Completes

Example 24: Conditional directive

Conditional directives should include positive, rather than negative, statements.

A negative directive is clear in the context of a procedure, but it translates poorly to a flowchart,where the Yes and No responses become confusing. In other words

If the quantities do not match, goto task #3. Otherwise, goto task #11.

is better written:

If the quantities match, goto task #11. Otherwise, goto task #3.

Example 25: State directives in the positive

A conditional directive may specify two or more conditions.

If only part A is complete, goto task #4. Otherwise, goto task #6.

Example 26: In a two-part conditional directive, the second condition is specified with the wordotherwise


32/60



Chapter 1 - Page 26

If only part A is complete, goto task #4.

If only part B is complete, goto task #6.

If both part A and B are complete, goto task #8.

Example 27: In a multiple conditional directive, each condition is explicitly stated

10. Verifies that the tax code changes have been entered correctly on the TaxCode Maintenance form.

If the tax code changes have been entered incorrectly, goto task #8.

If Section B of the form has been completed, goto task #11.

If Section C of the form has been completed, goto task #13.

If none of the above, goto task #16.

11. Verifies that the ...

Example 28: Multiple conditional directives

When conditional directives are used, there must be at least one directive that points to taskswithin the same task segment.

The following example shows an improperly constructed conditional directive.

9. Files the shortage report in the component shortage file, sequenced by date.

Not allowed:

If a work order requires modification, gotoReleased Manufactur in g OrderChange [PROxxxxx ]. Otherwise, end of activity.

The correct construction is:

8. Notifies the production ...


End of activity.

Goto Released Manufactur ing Ord er Change [PROxxxxx]

Example 29: Incorrect and correct directive construction


33/60



Chapter 1 - Page 27

The sequence of conditional directives is meaningful. That is, each directive carries an implied"no" to all preceding directives.

In the example below, the second directive assumes that tax code changes have been enteredcorrectly. The third directive assumes this too, and it further assumes that Section B of the formhas not been completed.

10. Verifies that the tax code changes have been entered correctly on the Tax

Code Maintenance form.If the tax code changes have been entered incorrectly, goto task #8.

If Section B of the form has been completed, goto task #11.

If Section C of the form has been completed, goto task #13.

Otherwise, goto task #16.

Example 30: Meaningful sequence of multiple directives

Tasks are numbered sequentially, regardless of the branching within the task segment.

If the order is from an international customer, goto task #9. Otherwise,goto task #10.

Sales Representative

9. Instructs the customer to forward a Letter of Credit to the corporate creditdepartment.

Goto task #12.

10. Determines the tax status of the sales order.

11. Records the tax status on the Customer Order Worksheet.

12. Determines whether the order ...

Example 31: Tasks are numbered sequentially, no matter what.

Whenever the next task in a sequence is notlogical, the alternative action must be specified inthe form of a directive.

In the following example, task #10 does not follow task #9; therefore, a directive must be usedto point the user to the correct task.

Sales Representative

9. Instructs the customer to forward a Letter of Credit to the corporate creditdepartment.

Goto task #12.

10. Determines the tax status of the sales order.

Example 32: Tasks are numbered sequentially, no matter what.

More examples of Conditional Directives are at the end of this document. See ExampleDirectives.


34/60


Task Segment: Unconditional Directives

Chapter 1 - Page 28


An unconditional directive specifies a single jump or path, without an If condition.

Unconditional Directives

Point to the task or activity to be performed next, no decisions

Are in bold text

Begin with one of the key phrases Goto

Stop and complete

End of activity

A "Goto" directive after an End of activity, may only point to another procedure and not a task orsupporting document.

Clicking on "Goto" or "End" on the Author toolbar will present two unconditional directives.

Goto task #?.

End of activity.

One other unconditional directive that you may choose to use is "Stop and Complete." You use

the directive style and point the actor towards another procedure or instruction.Stop and complete Invoicing [PRO1027Y].

An unconditional directive may include a simple qualifier, such as "as required" or "as needed."


End of activity.

Goto Released Manufactur ing Order Change [PROxxxxx]

Example 33: Unconditional Directives

The last task in a procedure must be designated with anend of activitydirective. That is, anend-of-activity statement:

must follow the last task in the procedure must follow the last task in each conditional path

If a procedure branches into paths that do not reconverge, an end of activitymust be used todesignate the end of each path.

The end of activity directive indicates that the activity has been completed. When aprocedure includes several distinct paths, the end point for each path must be indicated orthe user may perform tasks that are inappropriate.

The writer must take care that "end" is specified only at the appropriate points. Although itseems logical at times to specify "end" when a particular actor's tasks are completed, thewriter must ensure that "end" is specified only when all appropriate tasks have beencompleted.


35/60



Chapter 1 - Page 29

If the completion of one activity triggers the commencement of another activity, the subsequentactivity is identified in a directional note following the end of activitydirective.

The activity is identified only when it is supported by a procedure.

35. Forwards the order action report to each Production Control Planner.

End of activity.

Goto Manufactur ing Order Release [PROxxxxx]

Goto Released Manufactur ing Ord er Change [PROxxxxx]

Example 34: Unconditional directives that point to another procedure.

Sometimes conditional directives describe two distinct paths, with each path describing all thetasks needed to complete the activity. For example, a user may perform tasks #2 through #10under one condition, and tasks #11 through #20 under another condition. If the activity iscomplete after performing tasks #2 through #10, then you must indicate task #10 as an endpoint.


36/60


Task Segment: Parallel Directive

Chapter 1 - Page 30


A Parallel directive may be used to specify two or more sets of tasks that should be performedat the same time.


Parallel directive statements must:

Be formatted with the Directive paragraph style.

Use the following language and syntax:

In parallel: goto task #?, goto task #?

Begin with the phrase In parallel:

Use the text string goto task # to point to the appropriate tasks

Example where two actors perform tasks in parallel


37/60



Chapter 1 - Page 31

Example where three actors perform tasks in parallel

Best Practice Recommendation

When using parallel directives, include a task informing the appropriate actor to wait for allincoming parallel tasks to complete before continuing. In the above example, task 9 instructs the

Actor 1 to verify active tasks are completed before continuing.


38/60



Chapter 1 - Page 32

Converting Visio, XPLD, and BPMN flowcharts to Tutor format

With Tutor R14, it is possible to automatically convert standard Visio, XPDL, and BPMN files toa Tutor narrative format. Parallel tasks are commonly depicted in these flowchart formats.Converting parallel tasks to a narrative sequence is automated using specific rules andassumptions.

When BPMN flowcharts containing parallel tasks are converted from BPMN format to Tutor

narrative format, a task is added to the narrative procedure depending on the type of BPMNsymbol used.

The following table describes the task text that is added to the Tutor document when the mergeor join BPMN symbols are converted to Tutor narrative format.

BPMN symbol BPMN Notation Task added to narrative sequence

AND merge or join Verify all parallel tasks are complete and continue.

OR merge or join Verify active parallel tasks are complete and continue.


39/60


40/60


Task Segment: Qualifiers

Chapter 1 - Page 34


A qualifier is used to specify a condition associated with secondary tasks.

For example, the primary task approve purchase ordersmay have different secondarytasks depending on the outcome of each review. In such a case, a qualifier may be used tospecify the conditions.

12. Approve purchase orders.

Review each purchase order.

Purchase order approved

Sign the purchase order.

Purchase order rejected

Note changes on the purchase order.

Do not sign the purchase order.

13. Forward

Example 38: Qualifier paragraph style

Since secondary tasks are unnumbered, the qualifier does not point to specific tasks (as adirective does); rather the qualifier groups secondary tasks by condition.

A qualifier appears between secondary tasks only.

Qualifiers are written as incomplete sentences, using as few words as possible to describe thecondition.

Qualifiers appear in boldface with an initial cap on the first word.

Punctuation is not required at the end of a qualifier.


41/60



Chapter 1 - Page 35

If the secondary tasks performed (under a task) are conditional, those conditions may bespecified using qualifiers.

2. Obtains the suppliers authorization to return the material.

Contact the vendor to negotiate the material return to the supplier.

Initial the Discrepant Material Report.

Return to supplier authorized

Obtain an authorization number from the supplier.

Record the authorization number on the Discrepant Material Report.

Return to supplier denied

Indicate on the Discrepant Material Report that the return has beendenied.

Change the disposition on the Discrepant Material Report to "scrap."

Example 39: When a condition affects only a single step, the condition may be stated as part of the step. If

more than one step is affected, it is clearer to use the qualifier.


42/60


Task Segment: Note and Note List

Chapter 1 - Page 36

Task Segment: Note and Note List

Notes describe why a task or step is necessary. Notes may also be used to provide additionalinformation about the task or step.

Notes are stated in the second person.

Notes may be used for external procedure references:

Refer to Procedure Title [FileName]Refer to Receiving [PROxxxxx]

The AUTHOR.DOT template automatically indents notes. The paragraph styles used to formatnotes are:

Notes:

Note 1

Note 2

Note 3

Note Lists:

Note List 1

Note List 2

Note List 3


43/60


Task Segment: System References (Box Text)

Chapter 1 - Page 37


Tutor procedures may include references to other applications. For example:

1. Enter miscellaneous transactions header data into the system.

Oracle Inventory

N > Transactions > Miscellaneous Transaction

Miscellaneous Transaction

Refer to Performing Miscellaneous Transactions[../INV/@MISC_TRX_MTL_TRX_HEADER]

Example 40: Box Text paragraph style for system references and navigations

These system references show a navigation path (in the box) and may be followed byreferences to the related Application Online Help, as needed.

For Tutor Publisher Reports, system references should be formatted according to the

following rules: A system reference must appear below a Task 1 paragraph. That is, system references

are always subordinate to primary tasks.

The primary task describes the intent or purpose of the application use.

System references are formatted in the Box Text style.

In the example above, each of the three lines in the system reference is a Box Textparagraph. When you press Enter at the end of a Box Text line, the box expands toaccommodate the reference.

The information in the system reference is sequenced as follows:

The first line in the system reference identifies the application.

The last line identifies the unique destination screen name. The lines in between identify the navigation paththat is, the path within the

application that leads to the screen.

Multiple lines may appear between the first and last lines.

The following conventions can be used in system boxes in Tutor documents:

Streamline 'how to' Window Navigations. For example:

(N) Invoice > Entry > Invoice Batches Summary (M) Query > Find (B) Approve

This simplified path translates to the following:

(N) From the Navigator window, select Invoice > Entry > Invoice Batches Summary.

(M) From the menu, select Query > Find

(B) Click the Approve button.

Symbols used for simplified navigation paths:

B = Click Button

H = Click Hyperlink

I = Click Icon

M = Click Menu item


44/60



Chapter 1 - Page 38

N = From the Navigator or begin Navigation

T = Click Tab

ST = Click Sub Tab

> = continue navigating

Example:

1. Enter Salespeople and Credit type.

Oracle Order Management

(N) Orders, Returns (M) Sales Orders (T) Order Information (T) Main (B) Action > SalesCredits

Sales Credits

References to E-Business Suite Online Help

You may provide references to related E-Business Suite help files if procedures are going toreside in the Oracle Applications Online Help Database. Please see Author Online Help forCapturing Application Help Targets.


45/60


External References

Chapter 1 - Page 39

External References

An External Reference is any reference (within a Tutor document) to another centrally controlledTutor document.

The tight integration of Tutor documents to one another is due to external referencesand linksincluded in each document.

When to reference related documents is a challenge for all document writers. For procedure

writers, there are a few things to consider:

Will too many references distract the reader and affect their understanding of thematerial

Will the references enhance or impair the performance of the end user

Will having an HTML link to the referenced document enhance or impair theperformance of the end user

Documents that provide helpful or more detailed information to actors performing the procedurecould be:

Navigation documents for screen instructions

Reference documents for look-up information

The use of a support document is typically triggered by a procedure, so the reference (link)FROM a procedure to the support document is the primary and most efficient point of reference.There is no need to reference BACK to the procedure from a form or reference document, asthe user can use the back button on their browser. If a form is referenced by nine procedures, itcould create confusion for the end user if the form contains links to all documents that referencethe form.

When the documents are subsequently converted to HTML, formatting links that will stay validor active for the life of the document becomes an even bigger challenge.

The Tutor Methodology for creating external references and linking to other documents issimple. It also minimizes the potential for broken links.

Maintaining external references and links among documents can get cumbersome. Fortunately,

Tutor Publisher reports show what support documents are referenced by what procedures andvice versa. Therefore, minimize external references to simplify on going maintenance.

Format requirements for Tutor Publ isherreports

The standard format for an external reference(one Tutor document to another Tutordocument) is: italicized document title followed by bracketed filename:

Invoicing [PRO1027Y]


46/60


External References

Chapter 1 - Page 40

Format requirements for HTML documents and hyperlinks

For HTML documents stored in the Oracle Applications Online Help database

Document Title followed by Filename in square brackets

Document filename preceded by the relative link text ../FND/@(../FND/@ is the relative link syntax required to resolve the HTML hyperlink to Tutor

documents in the Oracle Applications Online Help Database.) Document Title and Filename italicized

Document Title and Filename underlined if HTML hyperlink desired

Invoicing [../FND/@PRO1027Y]

For HTML documents stored in the same folder on a server

Document Title followed by Filename in square brackets

Document Title and Filename italicized

Document Title and Filename underlined if HTML hyperlink desired

Invoicing [PRO1027Y]

For links to a web site

Cite the name of the Web site and its complete URL address

Place the URL address in brackets

Underline and italicize the entire reference (name and address)

Oracle Corporation [http://www.oracle.com]


47/60


Job Title Syntax

Chapter 1 - Page 41

Job Title Syntax

Authors Update Distribution Feature requirements

Tutor Author includes a utility for repopulating distribution sections in procedures andinstructions. In order for this feature to work, the document must contain at least one Actor Barwith an associated task.

Job titles picked up by this utility and placed in the distribution section appear with a superscriptasterisk *at the end of the job title.

Job title entries in an Actor Bar and Activity Preface under the generic job title string mustconform to a certain syntax.

The distribution feature assumes that job titles are separated by the following words orcharacter:

and

or

, (comma)

Characters that are assumed to be part of the job title are:

& (ampersands) / (slashes)

- (dashes)

Correct Syntax for a single job title Incorrect Syntax for single job titles

Manager of R&D Manager of R and D

Manager R&D Manager, R&D

Manager R/D Manager, R/D

VP of Finance & Administration VP of Finance and Administration

VP Finance & Administration VP, Finance and Administration

Buyer-Planner Buyer, Planner

Buyer/Planner Buyer and Planner


48/60


Miscellaneous Style Standards

Chapter 1 - Page 42

Miscellaneous Style Standards

Phrases or clauses beginning with that isare set off with an em dash or parentheses.

7. Contacts the Owner about the discrepancy in the procedure.

The Owner is responsible for all content changes -- that is, changes relatingto how the activity is performed.

Example 41: Phrases beginning with 'that is'

Quotations marks are generally not used to emphasize words or phrases.

A word or phrase in a note may be emphasized using all caps.

Quotation marks may be used in notes to indicate jargon or terms that are being used in anonstandard way.

Words are not hyphenated to accommodate paragraph width.

Since all of Tutors text is formatted ragged right, hyphenation is unnecessary.

Compound words are hyphenated according to standard rules of grammar.

Words with the prefix nonare hyphenated only when joined to a word beginning with a capitalletter.

nonproduction

nonprofit

nonnegotiable

non-Tutor

The following words indicate preferred spelling:

Acknowledgment

Canceling

Canceled

Traveler

Compare with is preferred to compare to.

Within the context of a procedure, "compare with" is the proper form. "Compare with" meansto examine side-by-side; "compare to" means to make a comparison, e.g., comparing thisWriting Guide to a great literary work.

Determines whether is preferred to determines if.


49/60


50/60


Examples of Conditional Directives

Chapter 1 - Page 44

Examples of Conditional Directives

The following pages contain four examples of conditional directives (If statements).

Example 1, which reflects a simple If/Otherwise directive, shows how a directive canpoint to the wrong task.

Example 2 shows a multiple If statement and all of the gotchas that an editor needs tobe aware of.

Example 3 shows how a multiple If statement can be rewritten using qualifiers.

Example 4 shows an inappropriate multiple If statement -- that is, a multiple Ifstatement that is illogical because the paths are not mutually exclusive. (An Ifstatement, by definition, must define mutually exclusive paths. This example showswhy this is necessary.)


51/60


Sample Directives Example 1

Chapter 1 - Page 45


The following text demonstrates why it is critical to read each task sequence in its entirety when you are doing a logiccheck. By following the first path defined (where task #4 is followed by task #8), you can see that the requisition isnever forwarded.

4. Check the requisition for the required information.

If the information is complete, goto task #8. Otherwise, goto task #5.

5. Contact the Originator for the missing information.

6. Enter the information in the requisition.

7. Forward the requisition to the Department manager for approval.

Department Manager

8. Review the requisition.

The simplest solution is to change the directive to point to task #7 instead of task #8.

Most errors in logic wont be this easy to spot or this easy to fix. (Sometimes, a fix will require additional tasks.)Nevertheless, following each distinct path will help you identify missing or redundant information that is oftenoverlooked by the owner or auditor.


52/60



Chapter 1 - Page 46


The following is a directive containing multiple If statements. In this example, the paths are mutually exclusive.Notice thatGotostatements are required to specify the correct sequence of tasks.

3. Check the color of the selected M&M.

If the M&M is blue, goto task #4.

If the M&M is red, goto task #5.

If the M&M is green, goto task #6.

4. Put the M&M in the blue pile.

Goto task #7.

5. Save the M&M for Jane.

Goto task #7.

6. Eat the M&M.

7. Pass the M&M bag to the next person.

Its important to note that this directive implies that blue, red, and green are the only possible colors. If there areother possibilities, the final If statement should read.

If the M&M is neither red nor blue nor green


53/60



Chapter 1 - Page 47


The following shows how the previous multiple If statement can be rewritten using qualifiers.

The determining factor in choosing one construction over the other should be whether the information needs toappear on the flowchart. (Qualifiers do not appear on the flowchart.)


Blue M&M Put the M&M in the blue pile.

Red M&M

Save the M&M for Jane.

Green M&M

Eat the M&M.

4. Pass the M&M bag to the next person.

Note that in reorganizing this information, task #3 no longer leads logically to task #4. (In other words, task #3 nolonger provides adequate information.) Therefore, if this construction is used, task #3 should be rewritten as follows:

3. Disposition the selected M&M based on its color.


54/60



Chapter 1 - Page 48


Multiple directives that are not mutually exclusive will almost always create problems in logic.

In the example below, the conditions may all be true (or not true). As written, however, an M&M that is blue willnever be tested for Peanutness or for cracks. Likewise, an M&M that is not-blue and peanut will never be checkedfor cracks.

3. Check the selected M&M.

If the M&M is blue, goto task #4.

If the M&M is peanut, goto task #5.

If the M&M is cracked, goto task #6.

4. Record an entry under the Blue column.

Goto task #7.

5. Record an entry under the Peanut column.

Goto task #7.

6. Discard the M&M.

Goto task #8.

7. Place the M&M in the To Be Eaten pile.

8. Pass the bag to the next person.

If you come across a multiple If directive like the one above, one solution is to rewrite the information so that eachcharacteristic (blue, peanut, crack) is tested for separately. This method is preferred if the writer needs to emphasizeeach test.

See the next page.


55/60



Chapter 1 - Page 49



If the M&M is blue, goto task #4. Otherwise, goto task #5.

4. Record an entry under the Blue column.

5. Check the type M&M selected.

If the M&M is peanut, goto task #6. Otherwise, goto task #7.6. Record an entry under the Peanut column.

7. Check the M&M for cracks.

If the M&M is cracked, goto task #8. Otherwise, goto task #9.

8. Discard the M&M.

Goto task #10.



Other Options

Another option is to simply address all three tests in a single task.

3. Check the selected M&M for color and type, as well as for cracks.

4. Record an entry under the Blue column, if applicable.

5. Record an entry under the Peanut column, if applicable.

If the M&M is cracked, goto task #6. Otherwise, goto task #7.

6. Discard the M&M.

Goto task #8.




56/60


Terms and Usage

Chapter 1 - Page 50

Terms and Usage

Fileis used as the first word in a primary task or secondary task only when a physical documentfile is being referenced.

6. File the paperwork.

File the Material Requisition in the daily issues file, sequenced by MRnumber.

Example 45: Using the word 'file'

Retain(as the initial word in a task or step) indicates that a form or document is filed for futurereference; further, it indicates that there is no standard document file in which to place the form.

Retainsimplies that it does not matter (from a procedural standpoint) where the document iskept.

Record(as the initial word in a task) implies handwritten comments or entries, as in a log.

Updateindicates a modification to a computer database file or to a word processing file. Thisterm cannot be used to reference a physical document file.

Editrefers to the process of reviewing a document and recording comments on the hard copy.

Modifyis used to describe the entire process of editing and updating a document.

In most cases, "modifies" will be the preferred verb, since it covers the entire process."Edits" and "updates" should be reserved for those tasks that truly focus on the physicaldocument or the computer database.


57/60


Word Use

Chapter 1 - Page 51

Word Use

Don't use long words when short substitutes will do

Dont Use---Use

absolutely sure---Sure

accomplish---doadvance warning---warning

attempt---try

bad disaster---disaster

basic fundamentals---fundamentals

blend together---blend

blue in color---blue

continue on---continue

cooperate together---cooperate

deficiency---lack

during the course of---during

each and every---each OR every

end result---result

equitable---fair

final conclusion---conclusion

first and foremost---first OR foremost

forever and ever---forever

infrequent---rare

local residents---residents

major breakthrough---breakthrough

mix together---mix

new beginning---beginning

new innovations---innovations

new recruit---recruit

occurrence---event

partially damaged---damaged

personal friendship---friendship

qualified expert---expert

refer back---refer

requisite---required

square in shape, tall in size---Square, tall

terminate or ultimate end---end

utilize---use


58/60


Word Use

Chapter 1 - Page 52

Don't Use words with extra or padded syllables

Dont Use---Use

administrate---administer

discontentment---discontent

experimentalize---experiment

irregardless---regardlessorientated---oriented

preventative---preventive

Use compact substitutes for word phrases

Dont Use---Use

on the order of magnitude of---about

In order to ---to

in the nature of---like

in view of the fact that---since

give encouragement to---encourage

make an adjustment in---adjust

is equipped with---has

avail yourself---use

a majority of---most

take into consideration---consider

Large number of---many

Avoid tautology the use of words that duplicate the meaning of a word or wordsalready used

Dont Use---Use

basic principles---principles

hollow tube---tube

mutual cooperation---cooperation

personal opinion---opinion

exactly equal---equal

consensus of opinion---consensus

past history---history

ask the question---ask

still continues---Continues


59/60


Index

Chapter 1 - Page 53

Index

A

Activity Preface: example of, 15; formatting, 15; Generic

Actors, 17; requirement for, 7; standard wording of, 16;

standard wording, first line, 16; The Trigger, 16; what to

include in, 15Actor: implied, 21; multiple, 17

Actor Bar, 20

Actual practice: documenting, 13

Author.dot, 8, 14

B

Box Text, 37

C

Capitalization of: company, 43; department names, 43;

form titles, 43; job titles, 43; procedure titles, 43

Conditional directives: definition of, 25; sequencing, 27;

using multiple, 26

D

Data entry: as tasks, 33

Directives, 23; associating actors with, 24; multiple If

statements, 46; mutually exclusive conditions, 48;

rewritten using qualifiers, 47; simple, 45; unconditional,

25, 28; used with steps, 33

Distribution section: definition of, 12; standard formatting

of, 12

Draft: marking procedures as, 5

E

Effective date: replacing with draft, 5

Emphasizing words, 42

Endof activitydirective, 24; specifying multiple, 24

External procedure: formatting references to, 8; in a goto,

29; referencing in Scope, 9

External reference: definition, 39

External references: required format, 39

F

File names for procedures, 6

Flowchart segment, 7

G

Generic job title, 21; formatting, 17; standard wording of,

17; when to use, 17

Goto directive, 23, 30

H

HTML hyperlinks: required format, 40

Hyphenation: of compound words, 42; using, 42

I

Introductory Segment, 8; formatting, 8; section heading

sequence, 8; sections within, 7

J

Job titles: generic, 21; syntax, 41

Job Titles or Roles, 4

N

Note and Note List, 36

O

Otherwise: in conditional directives, 25

Owner: of a policy, 10

Ownership: definition of, 13; example of, 13; shared, 13;

standard wording of, 13

P

Paragraph styles: used in the introduction, 8; used in the

task segment, 14

Parallel Directive, 30

playscript format, 14

Policy section: definition of, 10Policy statement: examples of, 10; owner of, 10; using

boldface type, 10

Primary Tasks, 21

Prior Activity, 19

Procedure: reflecting actual practice, 13; segments in, 7

Procedure references: in Activity Preface, 19

Q

Qualifiers, 34; punctuation with, 34

Quotation marks, 42

Quotations marks: using for emphasis, 42

R

Responsibility Section: definition of, 11

Responsibility statement: standard wording of, 11

S

Scope: definition of, 9; example of, 9; standard wording of,

9

Secondary Tasks, 33; conditional, 35


60/60

Segments: of a procedure, 7

Steps: numbering, 33; vs. instructions, 33

Stop and completedirective, 24

System references: within tasks, 21

System References, 37

T

Task: definition of, 21Task #1: text prior to, 20

Task Segment: components of, 14; styles used to format,

14

Tasks, 21; implied actor for, 21; implied sequence of, 25;

logical sequencing of, 27; numbering, 14, 27; verb tense

in, 21; wording of, 21

Tense: used in introduction, 10, 11, 13

Terms and Usage, 50

U

Unconditional directives: qualifying, 28

V

Verb tense: used in introduction, 8