Fusion applications usage guidelines are internal-facing documents that information developers and designers use during the Functional Design Phase of the Fusion Applications Process Model to create prototypes for development. These documents are posted on the Fusion Guidelines, Patterns, and Standards Web site.

Create Fusion applications usage guideline using the FUD template, which you can access on the Fusion GPS Web site. All styles listed in the Guidelines for Writing Fusion Applications Usage Guidelines can be found in the FUD template.

This guideline document discusses how to:

• Structure usage guidelines.
  
• Handle miscellaneous style and grammar issues.

• Divide usage guidelines into sections.
• Streamline content.

Dividing Usage Guidelines into Sections

Ideally, all usage guidelines should follow a prescribed structure so that designers can find the same type of information about a topic in the same places within every usage guideline document. This predictability is what all readers of technical documentation crave. However, because the Fusion usage guidelines encompass a variety of topics, not all guidelines fit neatly into one structure.

This section suggests a document structure that works well for most types of guidelines; however, you may feel it necessary to include additional or different sections within your guideline.

When possible, follow this structure:

• Document title

Set the document title in Heading 2 style.

Use this wording for the document title: “<functionality> Guidelines”

Example: “Contextual Actions Guidelines”

• Summary paragraph

Provide an abstract of the functionality described in the guideline. Limit this summary to one or two sentences. Provide more detail in the Description and Purpose section.

Example: “Contextual actions provide related information and actions to users within the immediate context of the object instances upon which they act.”

• Description and purpose section

Set the description and purpose section heading in Heading 3 style (FUG template).

Use this wording for the section heading: “Description and Purpose”

Follow the section heading with a high-level overview of the functionality described in the guideline. Describe the general principles of how the functionality works and what it helps users accomplish. Consider using a bulleted list to enumerate the benefits of the functionality.

• Example section

Set the example section heading in Heading 3 style.

Use this wording for the section heading: “Example of <functionality>”

Example: “Example of a Contextual Action Dialog”

To ensure that designers understand the best practices for the functionality that you are documenting, follow the section heading with a well-developed example. After introducing the example, consider using a table to describe or define the various elements of a given function or using a numbered procedure to walk readers through how the functionality is intended to work. Include screen shots with call outs where helpful to illustrate different steps in the procedure.

For example, in the Record Information Guidelines, the example section introduces a screen shot of a Record Information dialog, followed by a table that defines the various fields in the dialog.

In the Contextual Actions Guidelines, the example section includes an introductory paragraph, followed by a numbered procedure that illustrates a user interacts with a contextual action dialog.

• Usage section

Set the usage section heading in Heading 3 style.

Use this wording for the section heading: “Usage”

Following the section heading, document the best practices for the different aspects of the functionality. This is where you can provide specific design details.

For example, in the Contextual Actions Guidelines, subtopic sections are used to document the format and style of various components of a contextual actions dialog (the title bar, the tabs, the icon button groupings, the menus, and so on). The Icon Button Groupings subtopic specifies exactly where on the dialog that designers should group the various icon buttons.

• Related documentation section

Set the related documentation section heading in Heading 3 style (FUG template).

Use this wording for the section heading: “Related Documentation”

Following the section heading, include an introductory sentence, followed by a bulleted list of links to related documentation.

Use this wording for the introductory sentence: “Here are links to some related documentation:”

Set bulleted items in B1 style.

Here is an example related documentation section:

Streamlining Information

Usage guidelines should be manageable in length. Evaluate usage guidelines of more than five pages to determine whether you can consolidate or eliminate information. Guidelines longer than this present challenges for readers who are looking for quick answers to their design problems.

Follow these guidelines:

• Write short paragraphs of text, with one strong idea per paragraph.
• Avoid documenting the obvious and intuitive, either with text or screen shots.
  Consider your audience, including information appropriate for designers and information developers only.
• Don’t repeat information with different phrasing—say it once.
• Define terms once and use the same terminology throughout to describe the same features or functions.
• Don’t repeat text or screen shots.
• Don’t extol the technology or feature; just explain the functionality.
• Remove excessive examples.

This section lists miscellaneous established style and grammar guidelines in alphabetical order by subject for some of the most common issues that appear in usage guideline documents.

However, Oracle Style Guide should be your primary source of information for style and grammar-related issues. Also refer to the Central Terminology Repository to ensure that you are using approved abbreviations, acronyms, and verbs (and not using rejected terms) in your guidelines.  

Abbreviations and Acronyms

Spell out the complete term the first time an abbreviation or acronym appears in each guideline. Then, show the abbreviation or acronym within parentheses. In subsequent references within the guideline, use only the acronym.

The Central Terminology Repository includes approved abbrevations and acronyms for Fusion.

Basic Writing Principles

By observing the basic principles of technical prose, you make information clearer and you simplify the work of your readers.

Follow these guidelines:

1. Use complete sentences, beginning with an uppercase character and ending with final punctuation.
2. Use strong sentences with clear subjects and strong verbs in the subject-verb-object order.
3. Use positive sentences to avoid confusion.
4. Use active voice where possible.
5. Use present tense rather than future tense, except when you are describing a future action.
6. Use short sentences (about 25 words or fewer) and short paragraphs (about three to six sentences).
7. Define new terms, including acronyms and other abbreviations.
   See the Central Terminology Repository for a list of approved terms.
8. Refer to terms consistently throughout (for example, don’t refer to IOMGR in one paragraph and IO Manager utility elsewhere).
9. Avoid jargon, slang, and idioms (especially those that refer to culture, folklore, and sports).
10. Use a neutral, adult-to-adult tone; avoid patronizing expressions.
    Consider the following guidelines about neutral tone:
    • Avoid any expressions that would offend the reader, such as sexist or racist statements, ethnic slurs, or libelous statements.
    • Do not use humor.
      What may be humorous to you, may not be humorous to someone else, and it presents problems for translation.
    • Use who or whom to refer to people, not that.
    • Do not use s/he; instead, use he or she.
      If possible, rewrite the sentence to use a neutral plural subject, such as developers or users.
    • Do not patronize your readers.
      Do not presume that a task is easy for your reader. Avoid words such as simply, easy, and just.

For more information about basic writing principles, see Oracle Style Guide, Writing Guidelines: Using Basic Writing Principles.

Captions

Include captions to identify and explain screen shots, diagrams, charts, or other illustrations (not tables).

Follow these guidelines:

• Place a brief, descriptive caption beneath the graphic to explain the specific content of the graphic.
• Capitalize only the first word and all proper nouns.
• Do not precede the caption with a figure number.
• Set caption in Caption style.
• Line up the caption with the preceding screen shot or illustration.

Contractions

Although Oracle Style Guide does not permit contractions in technical documentation, you may use the following contractions in Fusion usage guidelines:

• Contractions of the word not (for example, can’t, don’t, and so on).
• Contractions involving the verb “to be” (for example, you’re, it’s, and so on).
• Contractions of the word will (for example, you’ll).

Cross-References

Supplying effective cross-references provides readers with quick access to related information and reduces unnecessary duplication.

A typical cross-reference takes the following form:

"For more information about subject, see reference."

In general, there are two types of cross-references: see and see also. A see cross-reference provides links to information that is too lenghy to include in the text, but the reader needs it immediately. A see also cross-reference provides links to information that is helpful but not absolutely necessary.

Follow these guidelines:

• Include a see cross-reference in line with the text to which it corresponds or on a separate line (but not in the middle of a sentence).

Insert the word See before each cross-reference (or group of cross-references). (The word See is set in the default paragraph font, not italics.)

• Include see also cross-references in a see also subtopic section at the end of a section or subsection.

If a section or subsection contains subtopics, place the see also subtopic section following the last informational subtopic section. If this is not appropriate, use see references instead.

• To create a see also subtopic section, insert the words See Also in Subtopic style.

List the cross-references in Normal style under this subtopic section heading.

• Include a period at the end of a see reference, but not at the end of a cross-reference in a see also subtopic section.

Here is an example of a see cross-reference:

Here is an example of a see also cross-reference subtopic section:

For more information about cross-references, see Oracle Style Guide, Components of a Document: Cross-References.

Examples

Introduce each formal example with a complete sentence that ends in a period.

Example: “The following example illustrates a contextual action and how you would interact with a contextual action dialog.”

Graphical Usage Interface Elements

Standards and guidelines for many graphical usage interface (GUI) elements are discussed on the Standards and Guidelines page of the FusionGPS Web site. User interface standards maintain consistency across the product suite. This consistency not only increases ease of use, but also reduces development costs and portrays our products as coming from one company.

Heading Styles

Headings are major entry points that help readers find the information that they need.

Follow these guidelines:

• Use these heading styles:

• Do not include more than three heading levels in usage guidelines.
• Set headings in title case.
  Example: “Basic Layout of a Conceptual Action Dialog”
• Do not skip heading levels.
  For example, in the FUD template, don’t follow a Heading 2 with a Heading 4.

Lists

Use display lists to organize, clarify, and emphasize information. A well-constructed, carefully positioned display list speeds comprehension and helps users to locate, understand, and retain information.

Follow these guidelines:

• Use numbered lists when the order is significant or when a series is suggested.

Use numbered lists when the order is significant or when a series is suggested.
Set numbered list items in List Number and List Number 2 styles. Limit each listed item to one phrase or sentence. Place supporting information in a paragraph below the corresponding, set in List Continue (for first-level lists) and List Continue 2 (for second-level lists) styles.

• Use bulleted lists when order is not significant and when all items are of equal weight.

Set bulleted list items in B1 and B2 styles. Limit each listed item to one phrase or sentence. Place supporting information in a paragraph below the corresponding, set in Body Text Indent (for first-level lists) and Body Text Indent 2 (for second-level lists) styles.

• Introduce each display list with a sentence fragment, sentence, or paragraph.

When you precede the list with a complete sentence, you can end the lead-in text with either a colon (:) or a period (.). Choose a colon to end the lead-in text when the list entries are a natural extension of that text. The words the following or as follows often signal the need for a colon. However, if the sentence that introduces the list does not immediately precede the list items, end the final sentence with a period. When you precede the list with a sentence fragment, always end the lead-in text with a colon.

• Include at least two listed items but usually not more than seven items, plus or minus two.

If the entries are particularly long or complicated, even five entries may be too many.

• Include a single item in a standard paragraph.

If the first item is a complete sentence, all items should be sentences. If the first item is a noun phrase, all items should be noun phrases. If the first item starts with a verb, all items should start with a verb.

• Use the appropriate punctuation.

End punctuation is not required unless the listed entries are complete sentences, in which case, use end punctuation (usually periods) for all entries.

• Treat each list entry as a distinct element; do not connect display list entries with one another using conjunctions or punctuation (commas or semicolons).
• Limit lists to two levels.
• Follow these additional guidelines for procedures:
  • For procedures, begin the introductory sentence with the word To followed by a description of what you do in the procedure.

Example: “To set up customer profiles:”

• Begin each step in a procedure with an imperative verb.

Example: “Print the document.”

Set the step in List Number style.

Present any explanatory text as a new paragraph following the step. Set the supporting information in List Continue style. The explanation retains the indentation of the step, but it begins on a new line.

• If a procedure is long, organize the steps in subtopic sections, restarting the numbering at the beginning of each subtopic section.

If you use this approach, begin the subtopic section headings with gerunds and make them task-based. Introduce the subtopic headings with a standard introductory sentence and list. Set subtopic headings in Subtopic style.

• If a step is optional, precede the text of the step with the word Optional in parentheses, followed by one space.

Example: “(Optional) Void the draft.”

For more information about lists, see Oracle Style Guide, Components of a Document: Lists.

Notes

Use notes, caution, and warning notices with discretion to call attention to important hints, tips, guidance, and advice on using the functionality discussed in usage guidelines.

Follow these guidelines:

• Set the word Note, Caution, or Warning in bold and follow it with a colon.
• Include a tabbed space after the colon, and then begin the note text with a capital letter.
• Set all notes in Normal style.

Example:

For more information about note, caution, and warning notices, see Oracle Style Guide, Components of a Document: Notes.

Subtopics

Use subtopic sections to separate chunks of information that should be set off visually under a heading but that don’t deserve their own heading level.

Follow these guidelines:

• Use subtopic sections to introduce examples.
• Use subtopic sections to break down lengthy procedures.
  See Lists.
• Use subtopic sections for see also subtopic sections.
  See Cross-References.
• Set subtopic section headings in Subtopic style.

Tables

Use tables to present statistical information or facts that you can structure in rows and columns. Tables often provide a clearer, more concise picture of the relationships among items than can be described in words alone. The structure of the table itself conveys meaning.

Follow these guidelines:

• Introduce each formal table with a complete sentence that ends in a period.
  Example: “This table lists system requirements for different types of computers.”
• Include column headings and set these headings in table head style.
• Set table cells in Table style.
• Set any bulleted items in tables in TableBullet style; set any numbered list items in tables in TableListNumber style.

Word Spelling and Usage

Use the following resources to determine correct spelling and usage of terms:

• The Central Terminology Repository (access via the Fusion Terminology Web site).
• The Fusion Terminology Forum.
• Oracle Style Guide.
• Merriam-Webster Online.