Designing great online help and demos for enterprise apps such as Oracle Fusion Applications using Oracle ADF and Apps-UX design patterns and guidance. By Ultan O'Broin (@ultan) for Oracle UX Direct. More at: http://www.oracle.com/webfolder/ux/applications/UXDirect/index.html

1. Oracle Applications User Experience Direct
User Experience Direct (UX Direct) is a program by Oracle Applications-UX to provide user experience expertise to
Oracle customers and partners for their implementations, customizations, and usage of our enterprise applications.
The goal of this program is to enhance end user experiences during and after customer implementations and
improve user adoption of our enterprise applications.
User Experience Direct: Creating Embedded Help
the page by themselves? What components are causing
Overview
the problem? Is there too much information on the page
When strategically placed and well worded on an confusing users that a more progressive disclosure can
application page, embedded help enables users to address? Is the terminology on the page causing the
quickly complete tasks, avoid errors, and eliminate the problem? Are the labels familiar to your user's expertise
need for additional help, training, or help desk calls. and domain? Change the UI labels first, rather than
Embedded help is sometimes referred to as instruction or adding help. Refer to your UX Direct Heuristics
description text. Evaluation How-To Checklist.
3. Use Help Contextually
Place embedded help where users can easily see it while
performing their tasks. Make sure that the information
provided is relevant to the user and the task.
Embedded help explains to users the purpose or
meaning of a component, how to enter data and what 4. Apply Help Selectively
happens to it, and how to perform tasks and actions in a Use embedded help only when it may be needed by the
truly user-centered way, without leaving the page. Use user, not as a design feature to balance a page. Do not
this document to understand and design embedded help overload the page with unnecessary help, or with wordy
that enables users to work productively with an text, as it creates UI clutter, slows down users, and
application. detracts from usability rather than enhancing it.
Embedded Help Design Checklist 5. Keep Users on The Page They Are Working On
1. Understand Your Users Make embedded help all the assistance that users need
Before designing help, understand the audience that will so that they never have to leave the page they are
use it. What is the target user's level of expertise, domain working on.
knowledge, and skills? What tasks do typical users need Rely first on the usability intuitiveness of the page itself.
to perform with the application in their work? What is the Then pay special attention to the meanings of UI
frequency of the task performed? Users need less help components (if you cannot change the names), to user
for often-performed tasks. What is the complexity of the anticipation about required fields or what happens if the
task? Users need more help for more complex tasks. user leaves a field empty, to the downstream implications
Remember that different users may use the same page of user decisions or inputs (such as how data is used or
in different ways. Refer to the User Profiles checklist how the application will respond), or to any differences
from UX Direct. that might result from users choices or different
2. Find Usability Pain Points and Redesign selections.
Never use embedded help as a workaround for a major
usability failing. Locate the problem area, redesign the
page, and retest it. Then decide if you need to add
embedded help. For example, what high frequency tasks
are causing a problem? Can users quickly learn to use

2. 6. Focus on Text Quality These basic embedded help types may be called
different names across different Oracle applications, and
Write in plain language. Spell check your work. Improve
there may be different presentations possible too.
readability by keeping sentences short, avoiding
symbols, unfamiliar acronyms and abbreviations, 1. Instruction Help
parentheses, and semicolons. It is acceptable to refer to Instruction help takes the form of either static text on a
the names of user interface components in the text, but page or region or is shown in a note window when users
make sure those names are accurate and reflect what is activate a field or other editable component on the page.
actually on the page. Use action verbs where possible,
explaining to users how to use things or how the Use instruction text only when typical users fail to
application will use their inputs. Address the user as you, perform a task without help or are caused to stop and
and omit the word please. Be concise and avoid consider the implications or format of any data they
superfluous phrases such as used to, in order to, if you enter.
want to, and so on.
Static text explains how users typically use a page or
region on a page.
When using static instruction text for tips or other
productivity information, use a tip icon to call attention to
the information.
7. Match the Help Type to User Need
Static text on a page or region should not exceed two
Decide whether your embedded help is instructional lines in length. Place the text underneath a header or
(how to perform tasks or use a component) or descriptive subheader. Two or three uses of text on a page are
(describes the purpose or meaning of a component). acceptable, if necessary.
8. Let Users Learn from Help Their Way
Allow users to turn off embedded help after first use, or
by user preference, if your application supports that
functionality. Users will learn from embedded help, so Field-level instructional help enables users to enter the
they will not need it if they use the page frequently. correct data in a field (for example, the type or format of
However, do not substitute personalization ability for entered data) or to understand in advance how that data
concise and relevant positioning of help. Check your is used downstream by the application. Provide an
development guide for information on providing example if needed.
personalization features for embedded help.
Types of Embedded Help
There are two kinds of embedded help: instruction text
and description text. Each type is shown to the users in If the application validates the data entered in the field,
different ways. Using a simple embedded help typology integrate the field-level help with any error and warning
like this helps you to design consistently, use a common messages that appear if the wrong data is entered.
look and feel, tailor your application to the user more
easily, and increase learnability as users become familiar Check if you application’s development environment
with what each type of help does. supports delivered validators and converters (for

3. example, those offered by the Application Development the assembly” use a phrase such as “Display and modify
Framework) and use those components instead of flow schedules at the detail level of the assembly.”
writing instructional text for data fields.
Field-level help should be short, one or two sentences in
length at maximum, as a larger note window may
obscure other UI components or distract the user.
Use the imperative voice with action verbs for static
instruction text or note windows help to explain to users Use a definitional style for any help icon-based tooltips
what they need to do. For example “Select from all that explain the purpose or meaning of a component. Do
defined consolidation groups, including the consolidation not repeat the name of the component in the text, and
group created for your legislative data group.” omit leading articles from the text to make it concise. For
2. Description Help example, use a phrase such as “Record of anticipated
financial expenditures of any type” for the Encumbrance
Description help takes the form of tooltip text on prompt instead of “An encumbrance is a record of
components that explain the purpose of the UI element, anticipated financial expenditures of any type.”
for example, on links, tabs, icons, menu items, buttons,
and so on. It may also explain the meaning of a Conclusion
component using a tooltip activated from a help icon near Finally, remember that embedded help, like other user
a component (sometimes referred to as a terminology assistance components such as messages, online help,
definition). and so on, is part of the overall user experience.
Embedded help is intended to help users complete tasks.
Embedded help, correctly designed, enhances the
application while reducing the need for additional training
and support.
Approach the creation and usage of embedded help with
the same care as the rest of the application, using your
user-centered design materials available from UX Direct.
Use descriptive help in tooltips to tell users about the
component itself where there is no visible prompt or label
on the component, for example on some images or
action buttons.
Provide information about menu items, links, toolbar
buttons, and so on, where the name of that component
isn't sufficient to explain the component’s purpose or
non-obvious meaning.
Explain to users the purpose of the component, rather
than how to use it. For example, users know how to click
a link, but may not know what the link is for, so omit
phrases such as “Click the link” and similar
constructions. For example, instead of “Click this link to
display and modify flow schedules at the detail level of

4. 4

5. Copyright © 2011, Oracle and/or its affiliates. All rights reserved. This document is provided for information purposes only and the
Oracle Corporation
contents hereof are subject to change without notice. This document is not warranted to be error-free, nor subject to any other
Worldwide Headquarters warranties or conditions, whether expressed orally or implied in law, including implied warranties and conditions of merchantability or
500 Oracle Parkway fitness for a particular purpose. We specifically disclaim any liability with respect to this document and no contractual obligations are
Redwood Shores, CA formed either directly or indirectly by this document. This document may not be reproduced or transmitted in any form or by any
94065
means, electronic or mechanical, for any purpose, without our prior written permission.
U.S.A.
Worldwide Inquiries Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.
Phone
+1.650.506.7000
+1.800.ORACLE1
AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. Intel
Fax
and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are
+1.650.506.7200
trademarks or registered trademarks of SPARC International, Inc. UNIX is a registered trademark licensed through X/Open
oracle.com Company, Ltd. 0110