Help Framework Usage Guideline

RCUX Document Version 5.0.1 for Oracle® Fusion Middleware 11g Release 1 Patch Set 1 (11.1.1.2.0)
Last Updated 22-Dec-2010

FusionFX provides multiple methods of displaying Help within an application. The method used depends on the component used in each context, and the scope of information required.

Guideline Contents

• General Principles
• Types of Help
• Help Icon
• Instruction Text
• Static Instruction Text
• Field-Level Instruction Text
• Hint Text
• Description Text
• Help Display Methods
• Tooltips
• Note Windows
• Assessing User Need for Help
• Develop User Profiles
• Locate Problem Areas
• Determine the Scope of the Problem
• Combining Different Types of Help

Related Guidelines

Guideline	Section	For Information About
Language in UI	All	General directions on writing Help text.
Message Framework	Note Window	Use in conjunction with Help.

Related ADF Elements

Refer to the ADF Faces Rich Client demos page to find demos and tag documentation for the ADF elements related to this component:

ADF Element	Notes
Help Provider	Retrieves instruction text and Help icon definition text from the application's Help system, and provides the link from the Help icon to the related Help system topic.
af:noteWindow	Note window
af:icon	Help icon

General Principles

Purpose:

Help components assist users to work with an application by explaining:

• The purpose of a component
• How to fill in a field
• How to complete a task

Effective Help design depends on the same kind of information that results in successful application design—detailed knowledge of an application's users. See Assessing User Need for Help near the end of this guideline for guidance on determining the most effective and efficient methods of designing Help for users.

Description:

FusionFX applications may include multiple types of Help. The type of Help used depends on the components for which Help is being provided and the type and scope of information needed:

• Help Icon: Can be configured to link to a Help system, to display a brief description in a tooltip, or both.
• Instruction Text: Static text or a note window with directions or guidelines for performing a task.
• Hint Text: Text with field formatting and validation rules in a note window.
• Description Text: Text with a brief explanation of a UI element in a tooltip or a note window.

Help Icon with Tooltip

Instruction Text Below a Header

Hint Text for an Input Field

Description Text for an Iconic Button

Usage:

• Products should include Help only where users would be unable to complete the task without assistance. Limit the number of Help displays to avoid cluttering the page with excessive static text, Help icons, and pop-ups.
• Typically, excessive need for Help indicates that the application interface is too complex for its audience. Help is not a substitute for well-designed UI.
• For general directions on writing Help text, see the Language in UI guideline.

Types of Help

The following table summarizes the different types of Help available in FusionFX applications.

Type	Display Methods	Valid Components	Type of Information	Recommended Length (Including Spaces)
Help Icon	Secondary window	Headers Editable and read-only fields Web widget groups	Extended Help on performing a task or use of a component	Determined by external/separate Help system
	Tooltip (on hover)		Explains purpose of component	Up to 120 characters of unformatted text***
Instruction Text	Static text on page	Headers and content below the header	Directions to perform tasks on a page or region where a user may fail to perform a task unassisted	Up to two lines of text (400 characters)
	Note window	All editable components		Up to 160 characters of formatted text
Hint Text	Note window	Fields that accept direct user input	Formatting and validation rules	Up to 160 characters of formatted text
Description Text	Tooltip	All visible UI components Items within list-based components, except tables and tree tables Columns in tables and tree tables	Explains purpose of UI element	Up to 120 characters of unformatted text***

Help Icon

Purpose:

The Help icon can display definition text in a tooltip and a related topic in an external Help system.

Description:

• The Help icon can display information about its associated UI element in either or both of the following ways:
• A tooltip containing definition text is displayed on hover over the Help icon.
• A Help topic in an external Help system is displayed when the user clicks the Help icon.
• When used to display an external Help system, the Help icon provides a link to a URL associated directly with the current application, or at a centralized site, such as the Oracle Technology Network (OTN).
• The Help system window is displayed in kiosk mode (without menus and toolbars) at the default size of 650 x 450 pixels. Clicking another Help button refreshes the Help window with a new topic, and brings the Help window to the front.
• When used to display a tooltip, the Help icon is associated with definition text derived from the application's external Help system. This approach facilitates authoring and translation.
• The Help icon may be added to any of the following components. The placement depends on the type of component:
• The Help icon precedes the prompt in these components:
• Checkbox group
• Checkbox: True/False type only
• Input/Choose Color Selector field
• Input/Choose Date Selector field
• InputFile
• LOV choice list and input field
• Quick Search
• SelectRadio
• Radio button: True/False type only
• SelectShuttle
• Select-one and select-many choice lists
• Select-one and select-many list boxes
• Slider
• Spinbox
• Input/Output Text
• The Help icon is appended after element text in these components:
• Page or section header, including search panel header
• Table column headers
• TreeTable column headers

Help Icon Before Field Prompt

Help Icon Appended to Column Header

Usage:

• Excessive use of Help icons can make a page too busy. As a general rule, a short page should have no more than three Help icons, whereas a long page may have up to five Help icons.
• Make sure that Help icons are placed in separate container elements or are sufficiently far apart so users can clearly see that each Help icon is associated with a specific page element.
• The Help icon should link to information about the component or group of components with which it is associated. The Help topic title does not need to repeat the label of the component, but it should be phrased so that the relationship is obvious to the user. For example, a "Country" choice list associated with a telephone number field could link to a topic titled "National Telephone Formats."
• Help icon definition text should be used when needed to expand on or clarify the prompt provided with the associated component. For example, the Help icon tooltip associated with the "Country" choice list above could be: "The country where the call is received".
• Help icon definition text is subject to tooltip limitations—it must follow string length limits and use no text formatting. See Tooltips for details.

Instruction Text

Purpose:

Instruction text provides directions on performing a task or on use of a component.

Description:

• Instruction text is derived from the application's Help provider.
• Instruction text is displayed in two ways, depending on the associated component and the scope of the information:
• Static Instruction Text below a page or section header.
• Field-Level Instruction Text in a Note Window.
• Instruction text is supported for most elements that can have a Help icon. Tables and TreeTables do not directly support either type of instruction text, but widgets within cells may have instruction text.
• Both display methods support basic HTML text formatting.

Static Instruction Text Below a Header

Note Window with Field-Level Instruction Text

Usage:

• Instruction text should be used only when the typical user may fail to perform a task without assistance. Excessive use of instruction text clutters the page with directions or distracts users with note windows that may also obscure related page elements. To determine whether instruction text is needed, evaluate each page against its target user for:
• Complexity of UI elements: Some elements, such as tables containing LOVs, are challenging for many users, while others may be difficult only for inexperienced users.
• Complexity of task: Some tasks involve many interrelated objects, such as updating a BOM (Bill of Materials) with many lines and which may include child BOMs.
• Familiarity with processes and terminology, such as creating and submitting a PO (Purchase Order) or an ECO (Engineering Change Order) for approval.
• Instruction text should be brief, and provide only the information needed to complete the task.
• When writing instructions:
• Use imperative voice, such as "Enter your first name", instead of "You need to enter your first name". See the Language in UI guideline for more information.
• Avoid references to UI labels, such as "Search", and to object types, such as "Accounts". See References to Labels and Objects in the Language in UI guideline for an explanation of this restriction.
• Product teams should configure user preferences so that users can turn off instruction text when it is no longer needed.

Static Instruction Text

Purpose:

Provides page- or section-level directions below a header.

Usage:

• Static instruction text should be used to provide directions on performing a complex task or to indicate business rules or domain-specific information that may not be apparent to the user.
• Static instruction text pushes trailing content further down the page, so it should be provided only when the typical user may fail to perform a task without assistance. Do not include static instruction text under every header solely for the sake of consistency.
• Static instruction text is always placed beneath a header. The scope of directions depends on the header level:
• Page header: Directions that relate to the entire page.
• Section header: Directions that relate to the entire section, including subsections.
• Static instruction text should not exceed two lines of text (it will wrap automatically), or 400 characters, including spaces and punctuation.
• Individual words within static instruction text may be bolded for emphasis.
• Users are more likely to read and understand text if it is concise, well-phrased, and used sparingly. Consequently, restrict static instruction text to a maximum of three entries per page.

Field-Level Instruction Text

Purpose:

Provides directions on using an editable field.

Description:

• Field-level instruction text is displayed in a note window.
• Note windows appear on hover over a field or when focus moves to a field, depending on the type of component.
• The note window may also contain message text and hint text.
• See Note Windows for details.

Usage:

• Field-level instruction text should be used for two purposes:
• To help users avoid errors when filling out a field. Directions may include business rules that may not be apparent to the user. For example, a Priority field may accept only numbers one through five. Providing instruction text could help users avoid an error message.
• To provide an explanatory note about the field. The note could include domain-specific information or could explain the consequences of filling in the field.
• Field-level instruction text must be directly related to the field. Do not include other information in field-level directions. If general directions are needed, use Static Instruction Text instead.
• Excessive use of note windows can distract users from their tasks and obscure related page content. Field-level instruction text should be provided only when the typical user may fail to perform a task without assistance. Do not provide instruction text for every editable field solely to make them consistent.
• Note windows may also display field-level messages and Hint Text. To avoid excessively large note windows, field-level instruction text should not exceed 160 characters.

Field-Level Instruction Text with Explanatory Note

Hint Text

Purpose:

Hint text helps avoid user error by displaying formatting examples and validation rules for fields that accept direct user input.

Description:

• Hint text appears in a Note Window along with any instruction text or messages related to the field.
• Hint text is displayed automatically when product teams define formatting requirements in the component's converter or validation rules in the component's validator. In either of these cases, hint text cannot be turned off; however, product teams are not required to specify these requirements or rules.
• The converter controls formatting of values for date, time, color code, and file path formats.
• The validator verifies the acceptability of the values, such as ranges of valid values, or specific valid values.
• The following components support hint text:
• Input/Choose Color
• Input/Choose Date
• Input File
• LOV choice list and input field
• Input/Output Text
• Unlike instruction text, hint text does not support HTML formatting.

Date Field with Hint

Usage:

• Hint text should be phrased as clearly as possible to help avoid user error. The recommended structure for the hint text is different for formatting and validation rules, and varies depending on the type of field:
• For formatting hint text, provide examples or specify a syntax when an example does not illustrate the format:
• Date-Time Selector: "Example: 27-Jun-2008"
• File Upload: "Example: d:\reports\myReport.doc"
• Color Selector: "Example format: #RRGGBB"
• For validation rule hint text, specify acceptable values, such as:
• "Value must be an odd number."
• "Date must be after 1-Jan-2008."
• "Time must be before 10:00 P.M."
• Hint text is subject to tooltip limitations—it must follow string length limits and use no text formatting. See Tooltips for details.

Description Text

Purpose:

Description text can provide explanatory text for any visible UI component, and is especially useful for components that do not support other forms of Help, such as icons, images, and list options.

Description:

• Description text can be displayed in two ways:
• If the associated component supports Note Windows, description text is displayed after any instruction text. Note that this option is not recommended. See the Usage section for details.
• Description text for all other supported components is displayed in a tooltip. Components that can have description text in a tooltip are as follows:
• PanelAccordion
• Breadcrumbs
• Buttons
• Dialogs
• Form Layout
• Headers
• Links
• Media Player
• Menu items
• Page Stamps
• PanelBox
• PanelList
• PanelSplitter
• Progress/Status indicator
• SelectRadio items
• Search panel
• SelectShuttle items
• Select-one and select-many choice list items
• Select-one and select-many list box items
• Content Switchers
• Table and TreeTable columns
• Tabs
• Toolbars
• Trains
• Tree and Tree nodes
• Description text is not supported for Table and TreeTable rows or LOV list items.
• When description text is displayed in a tooltip, it overrides any default tooltips on the component, including tooltips showing the full text of truncated data.
• Tooltip-based description text appears for both read-only and editable components, but note window-based description text appears only for editable components.
• Neither description text display method supports HTML formatting.

Iconic Button with Description Text

Choice List Item with Description Text

Usage:

• Use description text for:
• All active and informational elements that do not have prompts or labels, such as iconic buttons and images.
• Elements that do not support other types of Help—such as menu items, command and toolbar buttons, and links—when their labels are insufficient to communicate their purpose or when the action performed has consequences that may not be apparent to the user.
• Individual list options, such as choice list items, when their labels do not clearly identify them. Do not provide description text for every item in a list solely to make them consistent.
• Do not use description text:
• To replace Field-Level Instruction Text or Help Icon definition text. Both of these types of Help are derived from the application's external Help system and are optimized for translation—whereas description text is hard-coded into each page by developers and thus is more difficult for translators to work with.
• To replace Hint Text. Hints are displayed automatically when product teams define formatting requirements in the component's converter or validation rules in the component's validator.
• Description text is subject to tooltip limitations—it must follow string length limits and use no text formatting. See Tooltips for details.
• Description text does not need to form a full sentence. Writers can use standard syntaxes to write description text for action-oriented components and for navigation-only components. See the Language in UI guideline for details.

Help Display Methods

Depending on the type of Help used, Help text can be displayed in three ways:

• Tooltips
• Note Windows
• Static text, see Static Instruction Text

See Types of Help for a list of the methods associated with each type of Help.

Both note windows and static text support limited HTML formatting. Refer to the ADF tagdoc for af:outputFormatted tag for more information.

Tooltips

Purpose:

Tooltips are used to display read-only Description Text and Help Icon definition text.

Usage:

• Tooltips can display only unformatted text without line breaks, although browsers may wrap the tooltip text.
• Tooltip text should be brief, and should not exceed 120 characters, including spaces and any punctuation. Long paragraphs of unformatted text are difficult to scan.
• Tooltips are to be used only for "supplementary" information. An application must be completely usable without tooltips.
• Because tooltips appear only on hover, they are not accessible to users who don't use a mouse.
• Tooltips disappear after a brief period of time (defined by the browser). Users might not have enough time to read and absorb long text strings before the tooltip disappears, and may have to display the tooltip repeatedly in order to do so.

Note Windows

Purpose:

Note windows are used to display Hint Text and Instruction Text in a pop-up dialog.

Description:

• Note windows are displayed in either of two ways, depending on the type of component:
• On focus, typically for components that allow direct user input. The note window is dismissed when focus moves outside the component.
• On hover, typically for components that do not permit direct user input. The note window is dismissed when the user moves the mouse off the component. Note: for accessibility, note windows that display on hover are also displayed when the component receives focus.
• The note window may contain multiple types of content, separated by a divider. The sequence of content is as follows:
1. Message text. See the Message Framework guideline.
2. Hint Text
3. Instruction Text
4. Description Text

Usage:

Note windows are reserved for read-only information:

• Note windows may not contain editable fields because note windows do not provide a mechanism with which to explicitly apply or cancel changes.
• Note windows may contain buttons, links, and images.

Assessing User Need for Help

Effective Help design depends on the same information as successful application design—detailed knowledge of the application's users. Some applications are used by a single type of user which exhibits common characteristics. However, most applications are used by different groups of users with differing software skills, responsibilities, and domain knowledge. Differing groups of users may spend their time working in different parts of an application; thus, Help must be tailored to meet the audience needs for each part of the application. The recommended process is to:

1. Develop user profiles
2. Locate problem areas of the application
3. Determine the scope of the problem

Develop User Profiles

Here are several questions that help develop user profiles. This information can be gathered in the early design phase:

• Will users perform the same sets of tasks with this software?
• Do users have a common technology profile (software skills, domain knowledge, expectations of software behavior)?
• Based on the answers to these questions, how many major groups of users are there, and what are their characteristics?

Locate Problem Areas

Here are several questions that help determine which groups need Help in various parts of the application. This information is available only after prototypes and pre-release versions of the application have been developed.

• Do different groups of users typically use different tabs or groups of pages in the application?
• Which high-frequency tasks do each group of users find difficult to complete successfully?
• On which pages do users perform these tasks?
• How great is the difficulty? Can they figure out how to do it by themselves? If so, do they remember how the next time they perform the task?

Determine the Scope of the Problem

Web applications have multiple methods of providing Help, each with a different scope (component, section, page, or group of pages). This information should be gathered before developing Help for the page whenever possible.

• Is the problem caused by a single component, or by the interaction of a group of components?
• Is the problem caused by a shortcoming in UI design that cannot be fixed for some reason, or by a lack of domain knowledge (not understanding technical terms, or not knowing which choice to make)?
• Will a brief set of instructions suffice to address the issue?

Combining Different Types of Help

It is recommended to first identify individual fields requiring Help and then determine whether more general information is required, as follows:

• Provide Description Text for every iconic button.
• If a field prompt or button label is not self-explanatory, and this cannot reasonably be fixed by editing the prompt or label, provide description text with a fuller explanation.
• If an editable field has formatting or validation constraints, use Hint Text. If additional directions or related information are also needed, use Field-Level Instruction Text.
• If a read-only text element, such as a column header, is not self-explanatory, use a Help Icon with definition text and a link to the Help system for further information if needed.
• If a list item requires additional explanation, use description text.
• When users need directions to complete a task that involves multiple components, use Static Instruction Text. If additional information is needed, provide a Help icon to link to the application's Help system.
• If an overview of a multi-page task or business requirements is needed, provide static instruction text and a Help icon to link to an overview topic in the Help system.