Trade Secrets of Embedded Field-Level Help Gary Etzel Tonya McKee Russ Ward

Overview 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? 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? 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? 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 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 Examples 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? 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 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 Help 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 (cont.) Advantages Great when it fits Disadvantages No standard location throughout application No consistency No “control” by technical communications staff

What’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 area of the dialog box Clicking the ? button and then clicking on an area of the dialog box.

What’s This? Help (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 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 ToolTips Advantages 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 Help A designated panel or area of the dialog box displays a description of the item that has focus.

Dynamic Field-Level (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 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 Logistics 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 Issues Limited screen real estate Embedded panel is not “standard”

SynerGEE 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 Technologies KeyWorks Software ( 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 You Do? Pulling in descriptions from a database or text file

Getting Started Foster opportunity Break into user interface design

Contact Information

Questions ???