How to Design Great Online Help and UPK Demos for Oracle Enterprise Applications


Published on

Designing great online help and demos for enterprise apps such as Oracle Fusion Applications using Oracle ADF and Apps-UX guidance. By Ultan O'Broin (@ultan) for Oracle UX Direct. More at:

Published in: Technology
1 Like
  • Be the first to comment

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide

How to Design Great Online Help and UPK Demos for Oracle Enterprise Applications

  1. 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 Online Help 1. Customize and Extend SafelyOverview When customizing or extending application software,Oracle applications use the best in intuitive user interface adjust help systems as well. For example, afterdesign, but users will turn to the online help as a valuable configuring a procurement application for your businesssource of additional information. User may want answers requirements, customize the help to reflect newto questions about using the application, to know how to functionality, procedures, best practices, or theachieve best results, to understand the business context purchasing policies in your enterprise.of use, to explore scenarios and examples so that theycan maximize the potential of the applications, and to Follow the information provided by Oracle whenlook up more technical information about back-end customizing and extending help. This ensures that thearchitecture and functionality so that they can configure existing help content is retained for backup and that anyand extend their applications to meet enterprise business changes have the right security privileges and willobjectives. survive upgrades and patches regardless of version or localization. Refer to your development and administrative guides. 2. Design for Searching and Reading Online Use a consistent format of wording for the titles of each type of help topic, and include key words that describe the content. This titling approach enables users reviewing search results to quickly select the right topics to answer their questions. Write help topics using a pyramid approach. Online readers prefer more important information first, so writeHelp, correctly designed and integrated, enhances the an introductory paragraph to grab the reader’s attentionuser experience and contributes to maximizing your and summarize the solution details that follow.return on product investment. Help topics can accelerateusers in getting up and running on an application,increase user productivity, and reduce the need foradditional training and help desk support.The guidance here reflects the latest in usability researchand best practices about how users look for andconsume contextual, task-based information online, aswell as how to leverage co-worker knowledge to get jobsdone efficiently and productively in the enterprise.Never write help as a long-term solution to a usabilityproblem. Instead, work with your help desk, the OracleUsability Advisory Board, and UX Direct team tocommunicate software usability requirements to Oracle.
  2. 2. Structure the rest of the content using clearly written Write a type of help appropriate for the user profiletitles, short paragraphs, lists, tables, and graphics. Keep (administrative, casual, executive, functional, orthe content concise, and minimize the need to scroll. technical). Refer to the UX Direct User Profile checklist to understand how the audience works with the application,Use formatting to highlight (in bold for example) the audience’s level of expertise, and what kind ofimportant information so that it stands out, but don’t information the audience might need and when.overdo it. Ask a selection of your users to review a draft version ofAdd search keywords, such as names of activities or your help content for functional and technical accuracy toobjects or desired results. Use words that your users are ensure that they can use the help to complete tasksfamiliar with, as well as official Oracle terms. Web server quickly. Use the feedback to refine the content beforelogs are a good source of user search terms. releasing it. 4. Provide for Versions, Promotion, and Feedback Ensure that your users know what version of the help they are using. Communicate a policy for change roll out, by software upgrade version or regular maintenance schedule, for example. Use a What’s New? file, updated topics feature, RSS feeds, email or forum announcements to communicate what content is new or changed. Review your web server’s logs for hit rates on each topic. Eliminate old and unused help. You may find that some topics are continually used (how-to, examples and policy- style information, for example), but remember usage mayAdd links to other relevant help topics. Users like to be vary by user profile. A “popular topics” feature can steeractive online. But don’t require users to click too many new users to key information quickly.times before they arrive at the information they need. If obsoleting help topics, use a redirect file so that links3. Adopt a User-Centered Writing Style do not break and users can update bookmarks.Write text using plain language. Use terminology thatsuits the domain and expertise of the reader, as well as Conduct surveys of help users. In the help topics, includeyour enterprise’s policies and procedures. a “Did this answer your question?” question or a “contact us” email link for feedback to your help desk or helpEnsure that the terminology reflects exactly the names of creators.labels and other components as they appear in the userinterface. 5. Define the Types of Online Help Required Use different types of help based on a user-centeredUse the help system’s glossary of terms, existing product design approach. Consider using the following types ofdocumentation, and sales collateral to find the right terms help topics based on the user, context, and informationto use. requirements.Keep sentences to 25 words or less. Spell-check the FAQscontent, titles, search keywords, and any text in graphicsfiles too. Frequently Asked Questions (FAQs) are a popular help format, as they provide targeted personalized answers to questions about using the application, such as how-to
  3. 3. task information, assurance in anticipation of actions, or for explaining application functionality and howexplanations of outcomes that expedite task flow components work together to deliver business objectives.completion and enhance productivity. FAQs are suitable Conceptual information is more suitable forfor all types of users. administrative, executive, functional, and technical users.An FAQ should not turn into a permanently asked Use tables to structure different options and choices, andquestion. Word to improve the feature’s usability so thatthe FAQ is eliminated in the next revision. Refresh your use graphics to show architecture and processing flows.FAQ list frequently. Work with technical and functional users as well as business analysts to understand application technicalIdeal sources of FAQ information are usability tests, web details and how these details relate to businessserver logs showing lengthy time spent on application objectives and task completion. Refer to functionalpages or search terms, support forum queries, and help design and business requirement documents. Use yourdesk calls. Monitor what issues users are reporting or user profiles to understand precisely what kind oftalking about on your email system, intranet wikis, or information the audience needs and what the audiencediscussion boards. will understand.Present related FAQs together so that users can easily Ensure conceptual information is specific to the task orrefer to additional topics if necessary. For example, use a business objective required. Generic information doeslanding pad page of all FAQs relevant to a particular task not help readers obtain the exact information that theyflow. need.Examples of FAQs are explaining what something is, Examples of conceptual help include information thatwhat happens if users perform an action, how users can explains critical choices about application options, howperform a certain task, or why users see a particular calculations or analytics are done, how information isoutcome. processed, how features work so that these features canConceptual Information be configured to meet business objectives, and how the application functionality integrates with other platforms orConceptual information help topics provide explanations services so that usability and performance is optimized.and the background concepts to specific activities. Thesehelp topics supply the basis for important decisions and Reference Information
  4. 4. Reference information help topics provide detailed needed and the exact steps required. Work withapplication information used by administrative and business analysts and functional administrators totechnical users for application planning, implementation, develop the examples relevant to your enterprise.and maintenance. Example scenarios and simulations might detail how to set up or use the application to obtain a requiredUse tables and lists to structure reference information, business objective, when or why to use a particularexplaining what the information is used for, along with application feature, and how to communicate a bestany options, parameter, or other settings. practice for your organization.Ensure that the information can be read online and when Recorded demos—or simulations—can introduce new orprinted. Check that tables do not crop when printed, as key functionality, show how the functionality is used, andthe users of this information will likely refer to the content explain complex steps that users might then like to tryoffline in a printed format. themselves.Examples of reference information include details aboutapplication extensions and integration, data exports orextracts, formula functions, formula types, interfacetables, parameters, application programming interfaces,and so on.Sources of information include technical designdocuments, development specifications, designrepository- or development tool-generated output, dataschemas, coding guidelines, and so on. Work with yourimplementation, development, and configuration teamsto understand the details and have subject matterexperts verify the technical accuracy.Scenarios and SimulationsApplication users need examples of how to use thesoftware to obtain specific results. Provide realisticworked examples to show how users can achieve The Oracle User Productivity Kit (UPK) is the perfectdescribed results, including a scenario about the result solution for creating demos, enabling you to easily create
  5. 5. contextual audio-visual simulations from a real create entries for each meaning, along with the contextapplication. of use.Examples and demos are appropriate for all users, Link to the glossary terms from references in other helpthough more technical users may prefer a text-based topics where these terms may appear and needexample to a richer media demo. explanation. Include synonyms and related terms within the glossary, as well.Thanks to YouTube, using videos to explain how to usesoftware is gaining acceptance. Create your own short Structuring the glossary into sections based on thevideos, using plenty of realistic scenarios, examples, and letters of the alphabet—or making the glossary easilypractices that users will recognize. Feature a respected searchable—increases the likelihood of your usersand acknowledged subject matter expert from your staff. finding the right definitions quickly.Glossary of Terms 6. Enable Users to Collaborate Around HelpA glossary of terms is an alphabetically sorted list of key Users want to leverage each others’ expertise, oftenterms that users will encounter while using the immediately after they try and solve an issue on theirapplication, along with definitions for the terms. own. Collaboration around help topics is an ideal way to facilitate such engagement. Oracle WebCenter technology, for example, enables users to share information easily, providing a social media-like experience for tagging, ratings, reviews, and discussion, adding more value to the help system.In your glossary, include any new domain-specific terms,as well as more common business and technical terms Encourage participation on related forums and rewardthat users will come across in your application or help. valuable contributions with ratings and kudos.Include acronyms, definitions, and symbols, as well as Diplomatically eliminate more controversial or noisywhat these terms mean. Glossary entries are suitable for contributions.all users. Moderate your discussion forums so that helpfulIf your enterprise uses a different term than the one contributions are maximized and discussions are steeredsupplied by Oracle (for example “grade” instead of in the right direction.“level”), then ensure that the glossary includes your termand a definition to match. Moderators should be experienced, respected users of the software or accredited professionals.The principle of a glossary is that each term has only onemeaning in that particular context. If there is more than Email and instant messaging can also be used toone meaning for the same term in different contexts, then exchange links to help topics and other sources of help.
  6. 6. Integrate your help system with help desk forums, stepped through their working application and required tointernal user discussion boards, wikis, and so on so that enter live data at their own pace.users can share their experiences. Breadcrumbs help users to understand their location inGenerally, enterprise help desks do not like nontechnical the overall help system by content organization, productusers searching on the Internet for solutions to internal hierarchy, or business process level, for example.problems. If users are permitted to search externally,make sure that the sources of the solutions are identifiedand that subject matter experts validate the solutionsbefore those solutions are applied or becomewidespread.Reputation of content and credibility of contributions isimportant in the enterprise. Establish ground rules so thatusers know how to behave online.7. Enable Contextual Use and Logical Navigation Create links that are logical in terms of navigation and context. Enable users to get to the table of contents andUsers must be able to access help contextually from the index and between help topics easily. For example, ifuser interface. using previous and next links between topics, use theseContext is usually provided using software-based IDs (or links in the order of task completion, but do not assumetargets) in the user interface to reference the help topics. that the user will enter the navigation path at theFor example, the Oracle Applications Help uses anchor beginning.names linked to the names of forms, windows, or pages. If assembling help topics into guides or book-styleWhen users ask for help, a context-sensitive help topic, containers, then name the books logically according torelevant to application user interface, loads. the user audience: user, developer, conceptual,In many cases, context can be applied automatically to reference guide, and so on.the help content when you create it; in others cases, 8. Apply a Consistent Look and Feelextensibility or development tools must be used. Apply a consistent look and feel in the help system byThe Oracle Fusion Applications Help and user referencing the same style sheet across all topics. Theassistance popup (UAP) Manage Custom Help option location of the style sheet can be easily determined fromenables users with the right privileges to edit help topics Oracle predefined help, or you can modify the style sheetor load new help topics linked to the business and page or supply your own.context. If you change the Oracle logo and other links about policy information in the predefined Oracle files, then remember to make these same changes to any new files that you create and add to the help system. 9. Include Graphics in Your Help Use conceptual graphics and diagrams to help users understand the information in the help topics, for example, how application functionality fits together, howThe Oracle UPK enables you to capture context decisions between options can result in differentautomatically as you record demos so that users can outcomes, and how typical business processes or taskswitch from a passive watching mode, such as See It!, to flows active watching mode, such as Do It!, where they are
  7. 7. Describe any graphical information in the topic text andinclude descriptive ALT text with each nondecorativegraphic for accessibility support. Use a smart strategy of single-sourcing any information that may be output to different formats for your online help, print manuals, or other deliverables. Single- sourcing and eReader formats are more advanced areas on which the UX Direct team can also advise you.Screenshots are difficult to maintain and can cause Conclusionaccessibility issues, so use them sparingly, if you must. Plan for help as part of your customization andConsider using recording demos or creating example extensibility efforts. User-center designed help, deployedhelp topics instead. contextually in response to user needs and business requirements, enhances your application’s usability andEnsure that the references in your graphics use the user productivity, adding positive value to the totalsame terminology and style as the text. Review both text application user experience.and graphics together against the user interface. Invest in your help design and deployment effort,Using a widely available desktop application to create understand the different help types, and understandeditable graphics files enables you to spell-check any when best when to use these different help types.text and easily edit files for updating. Remember that the users of such help are reading10. Address Content Format Questions because they want to achieve a result and complete their tasks quickly. The faster readers can find, absorb, andMost users are now comfortable with using HTML-based apply the information that they seek, the help systems and also with searching forinformation on the web or corporate intranets. HTML- Using this UX Direct guidance will help you deploybased materials are easier to create, maintain, and effective help and eliminate the wasteful RTFM mentalityproduce than printed manual formats (PDF, for example). of desperately—and often fruitlessly—looking forHTML also makes it easier to apply a common style assistance, which frustrates task completion efforts withsheet for formatting, enables easy copy and pasting of costly results.code examples (important in the enterprise space), and For more information on designing and deployingfacilitates collaboration through easier sharing of help effective help, refer to the UX Direct Heuristicstopics, text snippets, and graphics files. Evaluation How-To Checklist and the website andMore technical users (implementors, for example) may blog.want to refer to printed hard-copy manuals in PDF, readoffline, or view help using an eReader device.
  8. 8. 8
  9. 9. Copyright © 2011, Oracle and/or its affiliates. All rights reserved. This document is provided for information purposes only and theOracle Corporation contents hereof are subject to change without notice. This document is not warranted to be error-free, nor subject to any otherWorldwide Headquarters warranties or conditions, whether expressed orally or implied in law, including implied warranties and conditions of merchantability or500 Oracle Parkway fitness for a particular purpose. We specifically disclaim any liability with respect to this document and no contractual obligations areRedwood Shores, CA formed either directly or indirectly by this document. This document may not be reproduced or transmitted in any form or by any94065 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. IntelFax 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/ Company, Ltd. 0110