trade secrets of embedded field-level help gary etzel tonya mckee russ ward
DESCRIPTION
Who Are We? We are technical communicators at Advantica, a global leader in technical software and service solutions to the natural gas, electric, water, and petroleum industries. We document and provide input on user interface design for engineering software that tends to be data- intensive and computationally complex.TRANSCRIPT
Trade SecretsTrade Secretsofof
Embedded Field-Level HelpEmbedded Field-Level HelpGary Etzel Tonya McKee Russ WardGary Etzel Tonya McKee Russ Ward
OverviewOverview
• Who we are and the goals of our project• What is embedded help?• What is field-level help?• Advantages and disadvantages of different
implementations of field-level help• Demonstration of our implementations• Tools and technologies• Getting started• Questions?
Who Are We?Who Are We?
• We are technical communicators at Advantica, a global leader in technical software and service solutions to the natural gas, electric, water, and petroleum industries.
• We document and provide input on user interface design for engineering software that tends to be data-intensive and computationally complex.
Who Are Our Users?Who Are Our Users?
• Our users are engineers and operators that work at utility companies.
• They need to:• Know how to navigate and use the software to accomplish
basic tasks• Understand the theory and methods used in the
calculations • Know what data to enter in each field
About Our Project?About Our Project?
• Re-architect cumbersome legacy software application that required use of commands and keywords to accomplish tasks
• Focus on performance-centered design and usability based on recommendations of experienced users and support personnel
• Technical communications participated in requirements and design phases of the project
What is Embedded What is Embedded Help?Help?
• According to Cheryl Lockett Zuback’s Intercom article “What is Embedded Help? (March 2000).
“Embedded help is user assistance that is part of the behavior and real estate of the user interface of a software application, rather than a separate window that floats...above, or sometimes behind, a software application.”
Embedded Help Embedded Help ExamplesExamples
• Embedded help can take on many forms, including:• Stationary panes embedded in applications that offer
process-based or instructional help• Wizards that guide users through a process• Agents that take users to the appropriate dialog box or
perform actions based on the user’s response to a prompt.• Tips or descriptions on dialog boxes to give assistance at
the point of need
Why Embed Help?Why Embed Help?
• Embedded help offers users assistance at the point of need
• No need to access and search in an external source• Keeps users on task and does not interrupt workflow• Users see the embedded help as part of the
application rather than “help”
What is Field-Level What is Field-Level Help?Help?• Each text box, control, button, etc. on the screen has
a description.• Field-level help can be very useful for data-intensive
applications. • Several approaches to field-level help that we
explored included:• Stationary field-level help• What’s This? Help• Floating ToolTips• Dynamic field level help
Stationary Field-Level Stationary Field-Level HelpHelp
• Tips or description inserted directly on dialog boxes by the developers
• Provided on an as-needed basis, as determined by the developer
Stationary Field-Level Help Stationary Field-Level Help (cont.)(cont.)
Advantages• Great when it fits
Disadvantages• No standard location throughout application• No consistency• No “control” by technical communications staff
What’s This? HelpWhat’s This? Help• The user can get a
description of any part of the window or dialog box by:
• Selecting Help > What’s This?then clicking on the item
• Right-clicking on an areaof the dialog box
• Clicking the ? button and then clicking on an area of the dialog box .
What’s This? Help What’s This? Help (cont.)(cont.)Advantages• Technology is available with established help authoring tools• Already included with many other applications, so users may
be familiar with it• Technical communications staff maintains and updates the
content, as needed.Disadvantages• User must request information instead of being brought to
them• Many users are not likely to know it exists without training
Floating ToolTipsFloating ToolTips• User hovers mouse cursor
over a screen item and a description displays.
• Commonly used for toolbar buttons, text that may be too long for the control, etc.
Floating ToolTipsFloating ToolTipsAdvantages• More obvious than What's This? Help• Eliminates an extra step to external documentation.• Consistency• Ideal for parts of windows or other GUI elements, such as
toolbar buttons, etc.Disadvantages• Constant "floating" could be irritating to a sophisticated user.• The volume of information needed to describe the field and the
ability link to external documentation might be limited.• Not sure who would maintain the text or how it would be
implemented.
Dynamic Field-Level Dynamic Field-Level HelpHelp
• A designated panel or area of the dialog box displays a description of the item that has focus.
Dynamic Field-Level Dynamic Field-Level (cont.)(cont.)
Advantages• No need to search for information about the field• Consistency• Technical communications staff maintains the content
Disadvantages• Panel takes up screen real estate
Our RequirementsOur Requirements• Each data intensive dialog box should contain an embedded
panel that can be scrolled to display the descriptions.• Developers must assign a unique identifier on every control on
the dialog box.• The description should change when an item is clicked or
hovered over in the dialog box.• A control or global preference should be available to minimize
or turn off the descriptions for advanced users.• Technical communications staff should maintain and update
the descriptions without requiring developer time.• ToolTips should be used in locations unsuitable for a panel.
Implementation Implementation LogisticsLogistics• When the requirements were handed off to
development, we had to work through several issues.
• Standards for setting up the IDs: numbering schemes and whether the developers would supply the numbers or we would create them.
• Storage of descriptions: TXT file, strings database, standard help project.
Implementation Implementation IssuesIssues• Limited screen real estate• Embedded panel is not “standard”
SynerGEE DemoSynerGEE Demo• Click or hover on any control to
change the description in the help panel
• “Expando” help button hides or shows the embedded help
• Panel provides links to more detailed conceptual and procedural topics in a secondary window
Tools and Tools and TechnologiesTechnologies• KeyWorks Software (www.keyworks.net/code.htm)• Developed by Ralph Walden, a business partner of
Cheryl Locket Zuback• MFC class that supports viewing CHM files with
mapped IDs• Shareware with open source code• Includes sample project and demo• Our development team made several customizations
to suit the needs of our application
What Else Could What Else Could You Do?You Do?
• http://www.pcd-innovations.com/infosite/dd_util.htm• Pulling in descriptions from a database or text file
Getting StartedGetting Started• Foster opportunity• Break into user interface design
QuestionsQuestions
???