Help Methods

General Description

Web-based applications include multiple methods to provide help to users. Each method satisfies user needs for different levels of information. This specification provides guidelines on choosing the methods which best match the needs of an application's users.

• Overview of Help Methods
  • Instruction Text
  • Hint and Tip Text
  • Information Messages
  • Bubble Help (ALT Text)
  • Content Container Text
  • Oracle Help for the Web
    • Context-sensitive Help
• Assessing User Need for Help
  • Develop User Profiles
  • Locate Problem Areas
  • Determine the Scope of the Problem
• Selecting Help Methods
  • Component-level Help
  • Section-level Help
  • Page-level Help
  • Matrix of Help Methods
  • General Rules of Thumb

Guideline Attributes

Interaction and Usage Specifications

Overview of Help Methods

Web applications provide six major types of Help, which provide information ranging from a single-line hint on use of a component to detailed descriptions of applications concepts and procedures. The primary Help methods are:

• Instruction Text
• Hint and Tip Text
• Information Messages
• Rollover (ALT) Text
• Content Container Text
• Oracle Help for the Web

Users may be allowed to turn off Tips, Hints, Key Notation, and Instruction Text in global Preferences, accessed with the global Preferences button. In global Preferences, users may NOT be allowed to turn off Inline Messages (Error, Warning, Cautionary Warning, Info. (inline w/widget), Bubble Txt, Content Containers, and Oracle Help for The Web. Refer to the Global Templates BLAF guideline, Preferences Global Page section.

Instruction Text

• The entire page
• A section of content
• A group of components within a section
• A table

• Instruction text should only be used when the typical user may fail to perform a task unassisted. To determine this, evaluate each page against its target user for:
  • Complexity of UI elements: Some elements, such as tables containing LOVs, are challenging to most users, while others may only be difficult 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.
• If a page does not need text, do NOT add text to make it consistent with other pages.
• Users are more likely to read and understand text if it is concise, well-phrased, and used sparingly. Consequently, restrict instruction text to a maximum of 3 entries per page, with a combined total of 6 lines.
• Instruction text should only explain the primary way to complete a task. Use Tip Text to explain ways to increase productivity, shortcuts, and alternate methods.

Tip Text

Tip text is used to call attention to useful domain or UI information that might not otherwise be obvious. This information may include reminders about organization policies, UI shortcuts or alternate ways to perform tasks, pointers to Preferences, pointers to the Help System (contextual help), or information on how the UI behaves, such as "Changes will be saved when you move to the next set of <objects>"

• The entire page
• A section of content
• A table, or a group of components within a section
• A single component, such as an action/navigation button, or link

Hint Text

Hint text is used to call attention to useful domain or UI information that might not otherwise be obvious. Typically it either points out information on how the UI behaves, specific domain information, or syntax rules to help the user fill out a specific web widget.

Hints are applicable to:

• A standard Web widget, such as a field, or radio button. (These tips are known as "Hints.")

• Tips for a page, section of page, table, or group of components include a Tip icon followed by the word "Tip" and one or two lines of text.
• Tips for action/nav. buttons or links include a Tip icon followed directly by one or two lines of text.
• Hints (Tips) for standard Web widgets consist of one short line of smaller text without a Tip icon.
• Content Container tips, which can be associated with a page or section of a page, may include an optional Tip or Quick tip icon followed by one or two paragraphs of text.

Information Messages

Information messages provide contextual information about business practices and methods, and may appear inline below a standard Web widget, in a message box, or in a message page. Web widget Information messages have the same font size and color as Web widget Tips, but are distinguished by their Information icon.

Information icons may be active, in which case they are linked to a message page with additional information, or passive, in which case they only serve to identify and draw attention to the associated message text. Passive icons are referred to as "Status" icons.

UI designers can use Information messages to explain domain terms; otherwise customers can use them to communicate their organization's policies and procedures. If users need directions on using a Web widget, provide them in page or section Instruction text, or in a Web widget Hint.

Note: See the Inline Messaging and Tips guideline for visual details.

Bubble Text

Content Containers

Oracle Help for the Web

Oracle Help for Web is a full-fledged Help and online documentation system, based on Oracle Help for Java. Like WinHelp and other Help systems, Oracle Help for Web is displayed in a separate window, allowing users to read directions while performing a task.

• Context-sensitive Help
• Table of Contents
• Index of keywords
• Full text search
• Online manuals
• Printable pages
• Quick Tours

For instance, if instruction text is used as a help method, the instruction text in the application page should describe either domain- or industry-specific issues, and/or describes how to use certain user interface components. If more information beyond what is displayed is necessary, then a Context-sensitive Help link may be appropriate.

Below are the recommended methods of Context-sensitive Help or accessing the Help System from within another help method on the page:

• Instruction Text - In addition to the text within the instruction text, a link directly to a specific topic in the help system may also be provided. For instance; "For more details, use the Help System." (Help System would be link text.)
• Tip Text - In addition to the text within the Tip, a link may directly to a specific topic in the help system may be provided. For instance; "For more details, use the Help System." (Help System would be link text.)
• Information Messages - Information messages provide contextual information about business practices and methods, and may appear inline below a standard Web widget, in a message box, or in a message page. There may be a contextual help link within the information message pointing the user to the topic in the help system.
• Bubble Help (ALT Text) - There should be NO link to the help system within Bubble Help.
• Content Container Text - In addition to the text within the content container, a link within the Content Container to a specific topic in the help system may also be provided. For instance; "For more details, use the Help System." (Help System would be link text.)

Assessing User Need for Help

Develop User Profiles

• 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 of the Application

• 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

• Is the problem caused by a single component, or by the interaction of a group of components?
• Is the problem caused by a UI glitch 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 short line of directions suffice to address the issue?
• Is there standard component-level Tip text for any of the application's groups of users? (for example, novice users may require a Hint below a Date field)

Selecting a Help Method

The answers to the preceding questions help you determine the type and amount of information required. The Help method(s) you select depends on the scope of the information required. Web application Help methods may provide information on:

• Individual components, such as fields and table cells
• Sections of content, including groups of components or an entire table
• An entire page, or a group of related pages

Component-level Help Methods

Help for individual components consists of Bubble text and/or one or two lines of terse Hint (Tip) or Information message text, and is defined in the Inline Messaging and Tips guideline.

Bubble text simply identifies components. Component-level Hints may be used to supplement Instruction text. Information messages may contain domain-specific information, such as an explanation of a label, or related organization policies and procedures.

Section-level Help Methods

• Instruction Text inserted directly below the section header.
• A Tip inserted within a given section, usually at the near to top or bottom of the section.
• A Content Container Tip.

Page-level Help Methods

• Users must click the Help button (a Global button at the top of the page) to see this information.
• The information presented must be comprehensive enough to address a range of user concerns, or else users will not return to Help to find answers.
• Inaccurate information in one Help topic can jeopardize user trust in the entire Help system, so Help must merit adequate development resources, and must receive the same level of QA review as the application.

Matrix of Help Methods

General Rules of Thumb

• If users are presented with detailed information on each component and section of the page, the application will become unusable, so it is essential to prioritize based on user need.
• If users need directions to complete a task, use Instruction text.
• If a brief amount of additional information is required, provide a Tip, but do not use Tips in place of Instruction text.
• If the directions are complex and require more than one paragraph, add an active Info icon to the Instruction text, or, if necessary, provide step-by-step directions in a Content Container.
• If the information required is too complex to be presented adequately for most users within the page, insert a Tip recommending that they choose the Help button for detailed directions.
• If a page has little text and additional information will be useful to users, but not necessary to complete the task, provide this information in page, section, or Content Container Tips, not in Instruction Text.
• Do not place more than three Tip icons on a page, and avoid placing them close together.
• Do not place more than two Content Containers containing Help on any page.
• If components requiring help are grouped, use a single Tip for the group. If the components are not grouped, and section-level Instruction text is not adequate, provide Hints on standard Web widgets, and a Tip on action/nav. buttons or links, if required.

Open/Closed Issues

Open Issues

Closed Issues

05.04.00 - separate component (inline messaging and tips) from page templates