trade secrets of embedded field-level help gary etzel tonya mckee russ ward

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

Contact InformationContact Information

• gary.etzel@advantica.biz• tonya.mckee@advantica.biz• russ.ward@advantica.biz

QuestionsQuestions

???