procedure style guide
TRANSCRIPT
-
8/13/2019 Procedure Style Guide
1/60
Procedure Style Guide
Oracle Tutor R14
October 2010
-
8/13/2019 Procedure Style Guide
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
-
8/13/2019 Procedure Style Guide
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
Sample Directives Example 2 ........................................................................................................................1-46
Sample Directives Example 3 ........................................................................................................................1-47
Sample Directives Example 4 ........................................................................................................................1-48
Terms and Usage ...........................................................................................................................................1-50
Word Use .......................................................................................................................................................1-51
-
8/13/2019 Procedure Style Guide
4/60
-
8/13/2019 Procedure Style Guide
5/60
Copyright Oracle, 2010. All rights reserved.
Student Guide Table of Contents
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.
-
8/13/2019 Procedure Style Guide
6/60
Copyright Oracle, 2010. All rights reserved.
Student Guide Table of Contents
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.
-
8/13/2019 Procedure Style Guide
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/13/2019 Procedure Style Guide
8/60
Copyright 2010, Oracle and/or its affiliates. All rights reserved.
Introduction - How to use this guide
Chapter 1 - Page 2
-
8/13/2019 Procedure Style Guide
9/60
Copyright 2010, Oracle and/or its affiliates. All rights reserved.
Introduction - How to use this guide
Chapter 1 - Page 3
Introduction - How to use this guide
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.
-
8/13/2019 Procedure Style Guide
10/60
Copyright 2010, Oracle and/or its affiliates. All rights reserved.
Developing a Procedure
Chapter 1 - Page 4
Developing a Procedure
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.
-
8/13/2019 Procedure Style Guide
11/60
Copyright 2010, Oracle and/or its affiliates. All rights reserved.
Developing a Procedure
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:
-
8/13/2019 Procedure Style Guide
12/60
Copyright 2010, Oracle and/or its affiliates. All rights reserved.
Developing a Procedure
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.
-
8/13/2019 Procedure Style Guide
13/60
Copyright 2010, Oracle and/or its affiliates. All rights reserved.
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
-
8/13/2019 Procedure Style Guide
14/60
Copyright 2010, Oracle and/or its affiliates. All rights reserved.
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.
-
8/13/2019 Procedure Style Guide
15/60
Copyright 2010, Oracle and/or its affiliates. All rights reserved.
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
-
8/13/2019 Procedure Style Guide
16/60
Copyright 2010, Oracle and/or its affiliates. All rights reserved.
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.
-
8/13/2019 Procedure Style Guide
17/60
Copyright 2010, Oracle and/or its affiliates. All rights reserved.
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
Tutor Software Requirement
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.
-
8/13/2019 Procedure Style Guide
18/60
Copyright 2010, Oracle and/or its affiliates. All rights reserved.
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.
Tutor Software Requirement
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.
-
8/13/2019 Procedure Style Guide
19/60
Copyright 2010, Oracle and/or its affiliates. All rights reserved.
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
Tutor Software Requirement
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
-
8/13/2019 Procedure Style Guide
20/60
Copyright 2010, Oracle and/or its affiliates. All rights reserved.
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
Tutor Software Requirement
Each paragraph must be associated with a valid Author.dot style.
Tasks are numbered sequentially, regardless of the branching within the task segment.
-
8/13/2019 Procedure Style Guide
21/60
Copyright 2010, Oracle and/or its affiliates. All rights reserved.
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
Tutor Software Requirement
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
-
8/13/2019 Procedure Style Guide
22/60
Copyright 2010, Oracle and/or its affiliates. All rights reserved.
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
-
8/13/2019 Procedure Style Guide
23/60
Copyright 2010, Oracle and/or its affiliates. All rights reserved.
Task Segment: Activity Preface (Generic Actor information)
Chapter 1 - Page 17
Task Segment: Activity Preface (Generic Actor information)
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.
Tutor Software Requirement
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
-
8/13/2019 Procedure Style Guide
24/60
Copyright 2010, Oracle and/or its affiliates. All rights reserved.
Task Segment: Activity Preface (Generic Actor information)
Chapter 1 - Page 18
section on Job Title Syntaxin this document to ensure accurate multiple job title entries in anactor bar.
-
8/13/2019 Procedure Style Guide
25/60
Copyright 2010, Oracle and/or its affiliates. All rights reserved.
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]
Tutor Software Requirement
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.
-
8/13/2019 Procedure Style Guide
26/60
Copyright 2010, Oracle and/or its affiliates. All rights reserved.
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.
-
8/13/2019 Procedure Style Guide
27/60
Copyright 2010, Oracle and/or its affiliates. All rights reserved.
Task Segment: Primary Tasks (Task 1)
Chapter 1 - Page 21
Task Segment: Primary Tasks (Task 1)
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.
-
8/13/2019 Procedure Style Guide
28/60
Copyright 2010, Oracle and/or its affiliates. All rights reserved.
Task Segment: Primary Tasks (Task 1)
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'
Tutor Software Requirement
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.
-
8/13/2019 Procedure Style Guide
29/60
Copyright 2010, Oracle and/or its affiliates. All rights reserved.
Task Segment: Directives
Chapter 1 - Page 23
Task Segment: Directives
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
Tutor Software Requirement
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
-
8/13/2019 Procedure Style Guide
30/60
Copyright 2010, Oracle and/or its affiliates. All rights reserved.
Task Segment: Directives
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.
-
8/13/2019 Procedure Style Guide
31/60
Copyright 2010, Oracle and/or its affiliates. All rights reserved.
Task Segment: Conditional Directives
Chapter 1 - Page 25
Task Segment: Conditional Directives
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
-
8/13/2019 Procedure Style Guide
32/60
Copyright 2010, Oracle and/or its affiliates. All rights reserved.
Task Segment: Conditional Directives
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 ...
9. Files the shortage report in the component shortage file, sequenced by date.
End of activity.
Goto Released Manufactur ing Ord er Change [PROxxxxx]
Example 29: Incorrect and correct directive construction
-
8/13/2019 Procedure Style Guide
33/60
Copyright 2010, Oracle and/or its affiliates. All rights reserved.
Task Segment: Conditional Directives
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.
-
8/13/2019 Procedure Style Guide
34/60
Copyright 2010, Oracle and/or its affiliates. All rights reserved.
Task Segment: Unconditional Directives
Chapter 1 - Page 28
Task Segment: Unconditional Directives
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."
9. Files the shortage report in the component shortage file, sequenced by date.
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.
-
8/13/2019 Procedure Style Guide
35/60
Copyright 2010, Oracle and/or its affiliates. All rights reserved.
Task Segment: Unconditional Directives
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.
-
8/13/2019 Procedure Style Guide
36/60
Copyright 2010, Oracle and/or its affiliates. All rights reserved.
Task Segment: Parallel Directive
Chapter 1 - Page 30
Task Segment: Parallel Directive
A Parallel directive may be used to specify two or more sets of tasks that should be performedat the same time.
Tutor Software Requirement
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
-
8/13/2019 Procedure Style Guide
37/60
Copyright 2010, Oracle and/or its affiliates. All rights reserved.
Task Segment: Parallel Directive
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.
-
8/13/2019 Procedure Style Guide
38/60
Copyright 2010, Oracle and/or its affiliates. All rights reserved.
Task Segment: Parallel Directive
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.
-
8/13/2019 Procedure Style Guide
39/60
-
8/13/2019 Procedure Style Guide
40/60
Copyright 2010, Oracle and/or its affiliates. All rights reserved.
Task Segment: Qualifiers
Chapter 1 - Page 34
Task Segment: Qualifiers
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.
-
8/13/2019 Procedure Style Guide
41/60
Copyright 2010, Oracle and/or its affiliates. All rights reserved.
Task Segment: Qualifiers
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.
-
8/13/2019 Procedure Style Guide
42/60
Copyright 2010, Oracle and/or its affiliates. All rights reserved.
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
-
8/13/2019 Procedure Style Guide
43/60
Copyright 2010, Oracle and/or its affiliates. All rights reserved.
Task Segment: System References (Box Text)
Chapter 1 - Page 37
Task Segment: System References (Box Text)
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
-
8/13/2019 Procedure Style Guide
44/60
Copyright 2010, Oracle and/or its affiliates. All rights reserved.
Task Segment: System References (Box Text)
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.
-
8/13/2019 Procedure Style Guide
45/60
Copyright 2010, Oracle and/or its affiliates. All rights reserved.
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]
-
8/13/2019 Procedure Style Guide
46/60
Copyright 2010, Oracle and/or its affiliates. All rights reserved.
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]
-
8/13/2019 Procedure Style Guide
47/60
Copyright 2010, Oracle and/or its affiliates. All rights reserved.
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
-
8/13/2019 Procedure Style Guide
48/60
Copyright 2010, Oracle and/or its affiliates. All rights reserved.
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.
-
8/13/2019 Procedure Style Guide
49/60
-
8/13/2019 Procedure Style Guide
50/60
Copyright 2010, Oracle and/or its affiliates. All rights reserved.
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.)
-
8/13/2019 Procedure Style Guide
51/60
Copyright 2010, Oracle and/or its affiliates. All rights reserved.
Sample Directives Example 1
Chapter 1 - Page 45
Sample Directives Example 1
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.
-
8/13/2019 Procedure Style Guide
52/60
Copyright 2010, Oracle and/or its affiliates. All rights reserved.
Sample Directives Example 2
Chapter 1 - Page 46
Sample Directives Example 2
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
-
8/13/2019 Procedure Style Guide
53/60
Copyright 2010, Oracle and/or its affiliates. All rights reserved.
Sample Directives Example 3
Chapter 1 - Page 47
Sample Directives Example 3
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.)
3. Check the color of the selected M&M.
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.
-
8/13/2019 Procedure Style Guide
54/60
Copyright 2010, Oracle and/or its affiliates. All rights reserved.
Sample Directives Example 4
Chapter 1 - Page 48
Sample Directives Example 4
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.
-
8/13/2019 Procedure Style Guide
55/60
Copyright 2010, Oracle and/or its affiliates. All rights reserved.
Sample Directives Example 4
Chapter 1 - Page 49
Sample Directives Example 4
3. Check the color of the selected M&M.
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.
9. Place the M&M in the To Be Eaten pile.
10. Pass the bag to the next person.
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.
7. Place the M&M in the To Be Eaten pile.
8. Pass the bag to the next person.
-
8/13/2019 Procedure Style Guide
56/60
Copyright 2010, Oracle and/or its affiliates. All rights reserved.
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.
-
8/13/2019 Procedure Style Guide
57/60
Copyright 2010, Oracle and/or its affiliates. All rights reserved.
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
-
8/13/2019 Procedure Style Guide
58/60
Copyright 2010, Oracle and/or its affiliates. All rights reserved.
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
-
8/13/2019 Procedure Style Guide
59/60
Copyright 2010, Oracle and/or its affiliates. All rights reserved.
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
-
8/13/2019 Procedure Style Guide
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