October 2009
By Nicoletta A. Bleiel

Nicky Bleiel is the Lead Information Developer for Doc-To-Help. She has 15 years of experience in technical communication; writing and designing information for software products in the documentation, media, industrial automation, simulation, and pharmaceutical industries. She is a Director at Large of the Society for Technical Communication.


nickyb(at)componentone.com
www.doctohelp.com


Blog: “Technical Communication Camp”

Further reading


Books

  • Cooper, Alan. The Inmates are Running the Asylum, 2004.
  • Cooper Alan. About Face: The Essentials of User Interface Design, 1995.

  • Galitz, Wilbert. The Essential Guide to User Interface Design, 2002.
  • Hall, Lynne. “Performance Support: Online help and Advisors.” International Encyclopedia of Ergonomics and Human Factors, 2006.
  • Nielsen, Jakob. Usability Engineering, 1993.

Other

  • DeLoach, Scott. “Best Practices for Embedded User Assistance” WritersUA Conference 2007.
  • Hughes, Michael. “Fattening the Long Tail through Progressive User Adoption.” Cutter IT Journal 20.4 (2007).
  • Zubak, Cheryl Lockett. "What is Embedded help?" Society for Technical Communication Intercom March 2000.
  • More information about C1Dynamichelp

Want to hear more about the topic?
Then visit Nicky Bleiel's Lecture Improving Software Usabilty with Embedded User Assistance at the tcworld conference in Wiesbaden, Germany.
Wednesday, November 4th, 8:45 - 9:30, room 12C

Improving software usability through embedded user assistance

Integrating user assistance into the software interface is one of the best ways to increase the usability of your software application and thus make your customers more satisfied and successful. However, embedded help has the reputation of being difficult to develop and execute. Let’s take a look at a solution that makes it possible to quickly include an embedded, dynamic help pane in a software interface.

Integrating user assistance into the software interface is one of the best ways to increase the usability of your software application and thus make your customers more satisfied and successful. However, embedded help has the reputation of being difficult to develop and execute. Let’s take a look at a solution that makes it possible to quickly include an embedded, dynamic help pane in a software interface.

The pane displays relevant help as the user navigates the interface. Furthermore, the information developer uses it to map the help topics to the interface. With proper planning and design, a single help file can be developed to work as embedded assistance and as a stand-alone help file.

The benefits of embedded help

Why is embedded help an excellent way to increase the usability of your software application?

Because embedded user assistance is task-specific, context-specific, and does not require users to search for it or ask the right question to find the answer. Unlike traditional online help, users continue their workflow and do not have to split their focus between two different windows. Best of all, users don’t see embedded help as help.

According to Wilbert Galitz in The Essential Guide to User Interface Design, a typical user interaction with documentation involves three steps: “(Users) need to find it, understand it, and apply that understanding to solve the task at hand.”

Online help is passive, with the user taking the initiative. Embedded help is non-intrusive and does not require the user to take the initiative, says Lynne Hall in the International Encyclopedia of Ergonomics and Human Factors.

Embedded help also encourages learning. According to Mike Hughes in the Cutter IT Journal, “users shift from a learning/exploration mode to a task execution mode … they stop exploring and experimenting.” Embedded help can delay that shift.

As Cheri Zubak, one of the pioneers of embedded help, has noted, “it’s help that is designed as software.”

Combine embedded help with an information-packed Start or Welcome page and you will ease users into the interface. This will increase the usability of your documentation set and your product.

An example of embedded help

In my project, I used a solution that made it possible to include an embedded, dynamic help pane in the user interface that displays the appropriate help topic as the user navigates, making the concepts and language of the interface clear.

This solution was a control (a visual component that can be snapped into an interface and configured) developed to my specifications. It includes a mapping interface, which information developers can use to visually map the help to the interface instead of using Context IDs. It has been developed by ComponentOne and named “C1Dynamichelp”. It can be used in any application developed in Microsoft Visual Studio.NET. The help file can be compiled as HTML help (a .chm) or web-based help.

Caption1: The Doc-To-Help interface with the embedded, dynamic help pane on the right. As the user navigates the interface, the appropriate help topic is displayed.

Designing user assistance for multiple uses

You can use the same help file or files for embedded help and standalone (traditional) help, if you design it properly. The same design will also work for your manual when you are single-sourcing.
Why is traditional help still necessary? Because the table of contents, index, and search are still necessary navigation aids and should be available if the user prefers to work that way.

To get started:

  • List the interface elements for which you want to provide embedded assistance. For example, if your application includes ribbons, accordion panes, and tabbed windows, you will want to have a help topic for each. These topics should be conceptual overviews that link to more detailed task and reference information.
  • List each dialog box that will require a help topic.
  • List the major functionality of the product. These topics will most likely be the top-level “books” in your table of contents.
  • Note your “housekeeping” topics (licensing information, trademark statements, etc.).

Once you have gathered all this information, put together a draft table of contents. Every topic that will be mapped to the interface should be marked for your reference.

Before beginning to write, you should create guidelines for each topic, so that each topic provides the appropriate amount of detail. For example, topics that explain interface elements should contain only short, introductory information that includes links to more detailed information. This also helps avoid repeating information among topics, or leaving out essential pieces.

Below are example structures for a user interface topic and for a dialog box topic:

Caption 2: An example structure for a user interface topic.

  • Breadcrumbs
  • Title
  • Image
  • Conceptual overview
  • Additional reference information
  • Related topics (“See also”)

Caption 3: An example structure for a dialog box topic.

  • Breadcrumbs
  • Title
  • Conceptual overview
  • Optional: Important Fact
  • “How to get there”
  • Task(s)
  • Dialog box field definitions
  • Related topics (“See also”)

Mapping and delivering embedded help

Mapping the help to the interface is handled with a mapping tool built into the control. All the mappings are saved to a single XML file that must be delivered to software development.

This is a five-step process that can be handled by the technical communicator or the software developer.

  1. Install the software application.
  2. Drop the help file(s) in the folder specified by software development.
  3. Open the mapping interface using a key combination specified by software development.
  4. Visually map the topics to the interface using the toolbar.
  5. Deliver the help file(s) and the mapping XML file to software development for deployment.

Caption 4: The dynamic help pane in three phases: with the mapping interface open and unmapped, after mapping, closed and ready for use.

Other tips for embedded user assistance

Following are a few things to consider when creating embedded user assistance.

  • Understand single-source authoring and concepts. Take advantage of conditional text, variable text, expandable or collapsible text, and other options your help-authoring tool (HAT) has to offer.
  • When designing your help, choose colors, fonts, and styles that work with the user interface.
  • Work with software development to determine the best position in your application’s user interface for the embedded help pane.
  • Once users are comfortable with the software, they may want to turn embedded help off. There should be a mechanism to allow this.
  • No topic should be a dead end. My recommendation: At least every topic should have a “see also” link to all of its subtopics, and every subtopic should have a link back to its parent.

Integrating other user assistance deliverables in the interface
Embedded help is just one piece of the deliverables set. In addition to the online help and manuals, information developers need to offer other elements to provide a user experience that serves all types of users and learning styles.

Deliverables may include videos and podcasts, quick reference materials, and tutorials, as well as websites, company forums, blogs, wikis, Twitter feeds, and other Web 2.0 initiatives. These should be incorporated into the Start or Welcome page. If you cannot do that, create a webpage that incorporates all of these deliverables and link to it from a menu or from the splash screen. Links to information about training courses, consulting options, upcoming conference exhibits, online newsletter subscriptions, and other useful materials will help users, even though they are not actual documentation.