| Fusion Embedded Help Content Guidelines | Version 2.0.0.0 |
| Fusion Embedded Help Types | |
Refer to the Embedded Help Pattern Set for details of when and where to use each type of embedded help.
There are five types of embedded help: Static Instruction Text, In-Field Help Note, Terminology Definition, Bubble Help, and User Assistance Popup (UAP):
1. Static Instruction Text
Examples
Create a new customer account profile. Provide the customer type, the organization billing level, and the account description.
- Or -
Review the payment priorities for all scheduled payments for each customer. Match the payment selection criteria to the approved credit ratings.
How this help type appears in the UI:
Figure 1: Static Instruction Text
2. In-Field Help Note
Examples
Adjust the liability of this invoice, and the gross amount of scheduled payments automatically adjusts- Or -
Select from all defined consolidation groups, including the consolidation group created for your legislative data group
Note: Some help and examples are generated automatically, so these should not be entered by content authors: data ranges, date formats, and so on. Check the list of ADF Validators and Converters hints and see the example in the In-Field Help Note Design Pattern.
How this help type appears in the UI:
Figure 2: In-Field Help Note
3. Terminology Definition
Examples
List of customers automatically excluded from a marketing activity
(for "Suppression List")
- Or -
Record of anticipated financial expenditures of any type
(for "Encumbrance")
Note: Unlike all the other embedded help content types, terminology definitions are often not structured as complete sentences but as dependent clauses.
How this help type appears in the UI:
Figure 3: Terminology Definition
4. Bubble Help
Examples
Display and modify flow schedules at the detail level of the assembly
- Or -Calculate the transfer price rate as an average of the supplied rates
Note: Like other help types, bubble help for buttons, links, and tabs uses sentence-case capitalization. However, bubble help for butcons and icons that have no labels must use title-case capitalization because that help is used as the Alt text (and therefore performs the same function of a capitalized label).
How this help type appears in the UI:
Figure 4: Bubble Help
5. User Assistance Popup
Examples
Enter and post journals, either on this page or through spreadsheet uploaded. Review journals and view projected account balances based on the journal adjustment amount. Also examine the details for journals created from subledger transactions.
- Or -
Define intercompany balancing rules, and a clearing company automatically balances your entries between balancing segment values. If you manually enter a clearing company in the journal, then it overrides the automatically assigned one.
How this help type appears in the UI:
Figure 5: User Assistance Popup
Refer to the Embedded Help Pattern Set for more details and examples of how and where each type of help appears in the UI.
| Embedded Help Content Principles | |
- Understand when to use each type of embedded help, and why the user needs it, by consulting the Embedded Help Pattern Set.
- Remember the ADF Validators and Converters and where they are used. Do not duplicate the hint information.
- Do not replicate the same content across different embedded help components (for example, do not use the same text in the Static Instruction Text and User Assistance Popup).
- Write in US English only (for example, "behavior," "organization," and "favorites") and spell-check the text.
- Write for the user so that the embedded help is part of the overall user experience.
- The embedded help text must be version-invariant and unlikely to be customized (that is, don't provide "customer policy" information-style information).
The development process will enforce the following length restrictions, so keep these lengths in mind when authoring and reviewing text. The specified character lengths include spaces and exclude any generated text.
| Embedded Help Type | Length (in US English) |
| Static Instruction Text | Less than or equal to 400 characters. |
| In-Field Help Note | Less than or equal to 160 characters. |
| Terminology Definition | Less than or equal to 80 characters. |
| Bubble Help | Less than or equal to 80 characters. |
| User Assistance Popup | Less than or equal to 400 characters. |
| Note: Each individual sentence must also be less than 25 words to make translation easier. Multiple clauses in a sentence should be avoided for the same reason. |
| Guidelines for Writing Global Embedded Help | |
- Write a Sentence in US English Using Approved Terms, Clear Subjects, and Strong Verbs
- Eliminate Wordiness
- Use Full Words, Not Shortcuts or Special Symbols
- Precisely Tell the User What to Do
- Use the Active Voice Where Possible
- Avoid Field and Label Names Where Possible, Paths, Product Names and Marketing
- Do Not Add Formatting or Link Markup, or Tokens
- Follow Specific Guidelines for Search Pages
- Follow Specific Guidelines for Read-Only Pages
1. Write a Sentence in US English Using Approved Terms, Clear Subjects, and Strong Verbs
- Static Instruction Text, In-Field Help Note, and User Assistance Popup text is written as a full sentence. Terminology Definition text is typically written as a sentence fragment.
- Begin each sentence with a capital letter.
- End all static instruction text and user assistance popups in periods. Do not end other embedded help types in periods (or other punctuation delimiters). If more than one sentence is used in these other help types, include periods at the end of the initial sentences, but omit the period from the final sentence. For example:
Enter acceptable deviations as decimal values. This attribute is assigned at the organization level
- Or -
Enter the percent of available tax to allocate to this line. If the corresponding amount is populated, then the percent is derived
- Within a sentence, use initial capitals on proper nouns only.
Exception: For bubble help used with butcons or any other icons that have no labels, use title-case capitalization because that help replaces the Alt text (and therefore performs the function of a capitalized label). For all other bubble help (for buttons, links, and tabs), use sentence-case capitalization, capitalizing only the first word and any proper nouns.
- Do not include locale-specific examples or references (for example, name formats, date and time formats, telephone or address formats, currency or numeric formats, and so on).
- Use the present tense instead of the future.
- Avoid implied subjects or verbs. For example: “This means the user can set up the billing level.” To what does this refer?
Examples
| Correct | Incorrect | Reason |
| Add contributors to the appraisal, and identify their roles in the process. | add contributors to the appraisal, and identify their roles in the process | Missing capital and period (Static Instruction). |
| - | Enter the planned date of the appraisal meeting, for example, 10/10/07. | Contains locale-specific date format. This information will be generated instead. |
| The skill level demonstrated by the appraisee | The skill level demonstrated by the person being appraised | The term to use is "appraisee." |
| Your information is not shared outside the organization | Your information will not be shared outside the organization | Use the present tense instead of future. |
| Account level transactions are plans that are associated with specific customer accounts and not all customer accounts. | This means that plans are associated with specific customer accounts and not all customer accounts. |
Implied subject based on "This means." Use a specific subject ("Account level transactions") instead. |
- Be direct and to the point; be precise, not theoretical.
- Do not write unnecessary help; work under the 'less-is-more principle.'
- Do not repeat the same content in different components.
- Do not use unnecessary articles. For example, say "Project can be viewed by any user in the enterprise" and not "The project can be viewed by any user in the enterprise."
- Every new word authored costs Oracle money to translate, so make every word count.
- Do not describe on-screen dynamics ("the window appears" and so on).
- Do not describe generic functionality, such as how to use the attachment feature, or "how to use the % wildcard to search" in a search field.
- Avoid the following constructs, or variants thereof: If you want or need to..., This is the page where you..., You are able to..., On this page, you can..., and You must. Instead, start with the actual verb, where applicable.
Examples
| Correct | Incorrect | Reason |
- |
Click the Search icon to search. The icon looks like a flashlight. | Unnecessary help. Rely on the usability of the UI instead. |
| - | Click Attachments (the icon looks like a paperclip) from the Menu bar. | Help for generic functionality, also unnecessary. Rely on the usability of the UI instead. |
| - | The search window appears next. | Unnecessary screen-based dynamics help. |
| Use the filter to find material requirements for each departmental task | If needed, you can use the filter to find material requirements by each departmental task | Theoretical condition (if needed) and use of you can. Be more precise. |
| Select the project name to group all jobs that belong to the same project | Select the project name if you want to group all jobs that belong to the same project | Use of if you want. Avoid these kinds of unnecessary phrase. |
| Change the print sequence of deliverables in the document. |
You can change the print sequence of deliverables in the document. | Use of you can. Avoid these kinds of unnecessary phrase. |
3. Use Full Words, Not Shortcuts or Special Symbols
- Write using only the approved words, acronyms, abbreviations, and the symbols.
Acronyms and abbreviations do not need to be spelt out on first use in embedded help. Spell them out in the glossary in the Oracle Fusion Applications Help.- Do not use contractions like it's, doesn't, can't, and so on.
- Do not use Latin short-cuts like et al, etc., e.g., i.e., or an ellipsis (...). ; instead, when needed, use the English equivalents (and others, and so on, for example, and that is).
- Use the plural form only instead of indicating a choice between singular and plural.
Examples
| Correct | Incorrect | Reason |
| Enter employee information | Enter employee number, department, etc. | Use of etc. Be exact instead. |
| You cannot override this value later | You won't be able to override this value later | Use of contraction won't. |
| Edit and review appraisals | Edit and review appraisal(s) | Use of (s) for plural and singular form. Use plural only. |
| Transaction authorization code obtained offline from the credit card processor | Txn authorization code obtained offline from the credit card processor | Unapproved acronym (Txn). Use the full words instead. |
4. Tell the User Precisely What to Do
- Use the imperative form to tell the user to select a value, enter information, click a button, or perform other actions to complete a task.
- Do not be vague with instructions.
- In help that tells the user what a field does, use an indicative verb whenever possible.
- Avoid using parentheses, which break up the flow of the text.
Examples
| Correct | Incorrect | Reason |
| Select the attributes that are important for rating the evaluation | You can specify which attributes are important for rating the evaluation | "You can"; instead, use the imperative Select. |
| Rate the appraisee for each competency | Appraise competencies ratings should be entered. | Use the imperative form of Rate instead. |
| Select a name in the table column to redefine the item | You can select a name in the table column to redefine the item | Use of the vague You can. Be precise and start with imperative verb. |
| Indicates whether the record has changed |
Indicator of whether the record has changed | The use of the indicative form of the verb (indicates) is better because it tells the user precisely what the field does, rather than what it is. |
| Organization payment methods define how the system uses payment sources, such as bank accounts, to pay employees at the Tax Reporting Unit level | Organization payment methods define how the system uses payment sources (such as bank accounts) to pay employees (at the Tax Reporting Unit level) |
Use of parentheses can be disruptive. Commas around parenthetical information is a better option. Other information previously in parentheses can be incorporated directly into the text. |
5. Use the Active Voice Where Possible
- Use the active voice when describing users actions or outcomes to user actions, where possible.
- Use pronouns like you and your, if necessary, to avoid the passive voice.
- Address the user as you, not his/her, the user, and so on.
- Generally speaking, when the system or application performs an action in the background, use of the passive voice is acceptable. However, when possible use the active voice by introducing the subject the application.
Examples
| Correct | Incorrect | Reason |
| Other users cannot view this banking information | This banking information cannot be viewed by other users |
Use the active voice, instead of the passive. |
| The employee must enter the appraisee competency ratings in this section. | The appraise competency ratings should be entered in this section. | Use the active voice, instead of the passive. |
| The application automatically calculates the total of interest due | The total of the interest due is automatically calculated | When the application or system is performing an action in the background, using the active voice is optional. However, when possible, use the application to apply active voice to the sentence. |
6. Avoid Field and Label Names Where Possible, Path Names, Product Names, and 'Marketing'
- Do not repeat the field or label name in the text unless absolutely necessary; instead, tell the user what action to perform.
- If the field or label name must be mentioned, then qualify it with a noun indicating the type of component
- Do not include navigation paths, application short codes (GL, FND, AP, and so on).
- Avoid information that "markets" product features.
- As a general rule do not refer to product names, unless you need to for usability reasons.
You may use the shortened version if it is clear to the user and you need to conserve space. For example, you may refer to Receivables instead of Oracle Fusion Receivables. Oracle always precedes the use of Fusion in product names.
The only approved product name acronyms are Oracle Fusion Human Capital Management (HCM) and Oracle Fusion Customer Relationship Management (CRM). When using these approved product acronyms, introduce the acronyms on the first use within the help using the full product name followed by the acronym in parentheses. Use only Oracle Fusion HCM and Oracle Fusion CRM on subsequent references in that help.
- When you use names of third-party applications, ensure that you are using correct legal names (for example, use those listed on the Microsoft trademark page).
Examples
| Correct | Incorrect | Reason |
| Save your changes | Click Apply to save your changes | Use of button name in text. |
| Rate the appraisee performance for each competency | Rate appraisees by clicking Competency > Performance Rating | Use of tab names and navigation paths. |
| Indicate the importance of this service request | Use the Severity field to indicate the importance of this service request | Unnecessary field label included in help text. |
| Create a hierarchy structure to chart your account segment values | General Ledger supports the creation of hierarchy structures for chart of accounts segment values. | Marketing-type content. Convey what to use in the UI if necessary, or provide no help. |
| By approving the template, you also approve any draft clauses listed in the Clauses Requiring Approval region. | By approving the template, you also approve any draft clauses listed in Clauses Requiring Approval. | Unqualified UI reference. Instead qualify the label with a noun (in this case, "region".) |
7. Do Not Add Formatting, Link Markup or Tokens
- Do not add formatting for colors, character formatting (bold, underline, italic, and so on), or layout (left or right align, new lines, soft-returns, non-breaking spaces, tabs, extra spaces, and so on). Do not use /n (new line) or /t (tab) characters to force newlines or tabs, or <BR> HTML elements for wrapping. Strings must be allowed to wrap automatically by the rendering technology.
- Do not add any links into the text (for example, pointers to other documentation or help, My Oracle Support notes, white papers, glossaries, and so on). Links from within embedded help content are not supported.
- Include all UAP text within one paragraph. Character or structural formatting (such as lists) is not supported. Links are generated search results and not hard-coded.
- Tokens are not supported in embedded help.
Examples
| Correct | Incorrect | Reason |
| Update your profile | Apply changes to update your profile | Use of italic formatting on Apply. |
| Enter the encumbrance value | Enter the encumbrance <a target="_blank" href="http://www.oracle.com/ glossary.htm#encumbrance">encumbrance</A> value. |
HTML Link added to a hosted glossary. These links are not allowed. Use a term definition instead. |
| - | For more information on entering deposit formats, refer to <a target="_blank" href="https://metalink.oracle.com/ metalink/plsql/f?...NOT,123854.1">MetaLink note ID: 123854.1</A>. |
External HTML link to another document. These links are not allowed. |
| Review the security level for users | Review the security level for each {USER_ROLE}. | Token {USER_ROLE} is used as way of indicating a user role. Tokens and such role striping are not supported. Use the full text instead. |
9. Follow Specific Guidelines for Read-Only Pages
|
|
| Related Information | |