RoboHelp Article

Creating Online Help (Part 1): Design and Development Considerations

Design Principles and Concepts

Use a task perspective instead of a system perspective

Imagine a person who has never used an ATM machine but would like to know how. Imagine the answer this person might hear after asking the ATM's engineer or creator how it works. The engineer may describe how the ATM functions electronically, in other words, the system operations and technical processes that make it work. None of this information, however, would actually help the user perform a practical task. In fact, it's unlikely that the engineer's information would interest that potential user at all. He or she wants only to know, for example, how to draw money from an ATM, or deposit a check, or use it in other ways that would transform it into a practical and useful tool. Thus, the potential user is uninterested in the engineering behind the ATM; instead, the user wants to know how to use it as a tool to fulfill a practical need.

To create good Help systems, technical writers must understand the users' needs. In so doing, technical writers will be able write Help from a task-perspective, anticipating the users' practical needs, instead of a system-perspective, which is the technical description of how something functions.

Layer your Help information for different audiences

Users will range from novices to expert. Layering information provides succinct information for the more sophisticated user, while providing avenues for novices to seek more detailed Help. Layering also accommodates situations where the inverse is true. Novices may only require a simple answer to a question, whereas the more sophisticated may want deeper, more involved explanations.

Examples of layering information

Macromedia RoboHelp provides many opportunities for layering information. By layering information, you provide users with various avenues to deepen or broaden their understanding of concepts and procedures—below I've listed some ways you can use RoboHelp to do so:

Figure 1a and 1b show how you use pop-ups and secondary windows to create a new layer of information.

Figure 1a. Before selecting…

Figure 1b. After selecting…

You can use pop-up and secondary windows to broaden a user's understanding of a term while maintaining the current topic in its current window. That way, users have a continuous experience instead of leaving the current window; they don't lose their focus.

In Figures 2a and 2b, see how you can use text-only pop-ups to create new layers of information in the form of brief definitions.

Figure 2a. Before selecting…

Figure 2b. After selecting…

In this example, novices see text-only pop-up links; brief definitions to terms they may not understand.

Figures 3a and 3b shows how you can use expanding hotspot text to create a new layer of information for those who seek it (from Microsoft Excel Online Help).

Figure 3a. Before selecting…

Figure 3b. After selecting…

Expanding hotspot text can be used to explain something with greater detail for those who need the additional information. Otherwise, the text appears only as simple bulleted or numbered text and reduces the overall length of the topic.

Figure 4a and 4b shows how you can add a layer of explanation through illustration using multimedia or graphic images.

Figure 4a. Before selecting…

Figure 4b. After selecting…

Creating a link to a multimedia demonstration helps novices better understand a procedure. Meanwhile, the more sophisticated computer user can just skip over this link.

Using analogies and overviews to explain concepts and illustrate processes

Often you can convey a complex technical concept better by making analogies to things outside of a technical context. For example, I've often given the following analogy and overview to those who are new to Help authoring on how to create a Help file:

"Creating a Help file first involves establishing a construction site. This in Help authoring is a “project folder.” In this folder, you'll assemble all the necessary components for the Help project you'll build.

"Next, ensure that you have the necessary information incorporated in your HTML topic files to build a basic project. HTML topic files are like the brick and mortar of a project you're building. They are absolutely required.

"Next create an architectural blueprint of what HTML files, and their position. The architectural blueprint determines the shape of the Help file to come. When using RoboHelp, the architectural blueprint is the Master Project File, known as either an MPJ file in RoboHelp versions prior to RoboHelp X5, or as an XPJ file as used in RoboHelp X5.

"Finally, motivate your hard-hat workers to take the HTML content and construct a Help system based on the architectural blueprint (our MPJ or XPJ file). The hard-hat workers in Help authoring are represented as the HTML Help compiler. A compiler is a program that follows an architectural blueprint (such as the MPJ or XPJ file) to organize Hypertext Markup Language-related content into a compiled HTML Help file, also known as a CHM file or “Chum” file."

Having used this analogy in the past, I have seen students quickly and easily associating HTML files as the bricks and mortar of their Help project, the MPJ or XPJ files as their architectural blueprints, and the compiler as the hard-hat workers, needed to produce a CHM file.

Using examples to explain concepts and illustrate processes

There's no better way to ensure that your users have the best understanding of a concept or procedure than to show them some examples of what you are referencing. Typically, after explaining a concept, you'll find yourself adding new information beginning with “For example.”

For example, the graphic illustrations above were my attempt to better convey how to layer information in a Help system—to display brief and succinct information for some users, while providing avenues for other users to deepen or broaden their understanding.

Page 3 of 5

Previous Page

Next Page