The Anatomy of a Help File: An Iterative Approach

Designing Help

When products have page-level or tab-level context sensitivity, the design process I am about to describe can very efficiently support iterative releases of testable code. We are using an open standard methodology called DITA (Darwin Information Typing Architecture) with an open source topic-mapping tool called Task Modeler. The DITA capability of semantically typing topics as Task, Concept, or Reference facilitates the approach I describe in this article, and the DITA mapping view within Task Modeler facilitates the design and file-stubbing steps I describe. However, applying this approach requires neither DITA nor Task Modeler.

The following overview summarizes the process for an iterative approach to creating Help:

1. Identify the pages that need context-sensitive Help. If the product has embedded Help, treat that as context-sensitive Help. You’ve merely removed the need for a user to click an icon or link.
2. For each of the pages the Help system supports, define a task-support cluster of Help topics. (I am about to discuss what that is.)
3. Stub the file structure—creating files that have topic titles and the required inter-topic navigation links, but not necessarily any of the content.
4. Write the task topics first.
5. Flesh out the clusters with the conceptual and reference topics.
6. Identify and write background and overview topics.

Task-Support Clusters

A task-support cluster is a closely associated group of Help topics you design specifically to meet the requirements of a user who is currently engaged in a task using the user interface. Its opening topic is called the keystone concept, and it is either a topic a user displays by clicking a context-sensitive Help link or the default topic in the embedded Help pane for a specific page. In designing the task-support cluster, make these assumptions:

• A user has the necessary computer and domain knowledge to be doing the task—although the user might lack the full knowledge or experience an expert would have. I call this assumption the “you must be this tall to ride this ride” principle.
• A user is in the right place to perform the task the user wants to do.

These assumptions will not be 100% true 100% of the time, but you are designing the primary user assistance experience at this point, not the complete user assistance experience. You can provide mitigation strategies for those users who do not fulfill these assumptions later. However, making these two assumptions lets you choose topics and write content that get the average user out of the Help and back on task within the application as quickly as possible.

A task-support cluster has the following elements:

• an introductory keystone concept topic—which is the target of a context-sensitive link in the user interface and provides a functional overview—what you can do on this page. It can also augment domain expertise by providing tips or examples that give insight into how best to use that page to accomplish user goals.
• task topics—which support the possible user goals for functions on the page
• any reference topics—which users might require in support of those tasks
• deep concepts—which, if appropriate, are more detailed than the keystone concept and present either more elementary information—for example, if the targeted task uses wildcards, how wildcard rules work—or more technical information—for example, if a targeted task initiates system activity that might be of interest to an advanced user who is trying to anticipate impact on network performance, how the system processes network traffic in the background. Either of these types of topics might be unnecessary clutter to the average user, but less-experienced or more-experienced users could find them valuable. However, deep concepts should still be closely related to the tasks a page supports.
• appropriate inter-topic links—which are links to other topics within the cluster

Figure 1 shows an example of a typical architecture for a task-support cluster.

Guidelines for Designing Task-Support Clusters

Here are some guidelines for designing task-support clusters:

• Do not provide extraneous links—links that do not apply to the targeted task. Avoid the temptation to link the Help topics from one task-support cluster to another. For example, a page for selecting recipients to receive alert notifications by email is only loosely related to another page for configuring email. Assume a user’s targeted task is to set up notifications, not configure email, and quickly get the user back to the user interface to finish that task. Certainly, you can point out dependencies and tell the user how to get to dependent pages, but let the topic-support clusters for those pages pick up the burden should the user need help there.
• Include navigation instructions in all task topics, either as explicit steps in the procedures or as links to navigation tasks. This mitigation accommodates users who get to Help topics through the Help table of contents, index, or search.
• Be parsimonious with content and navigation. Your primary goal is to get the user back on task as quickly as possible.

But what if a page is very simple and creating a task-support cluster would be overkill? Then don’t do it. If a single task topic with a well-written goal or context statement can support a user goal, just create that. Or if Help cannot add any information beyond what the text in the user interface already provides, don’t add a context-sensitive Help link to that application page.

On the other hand, what if the task touches on broad areas of domain expertise that some users may lack―failing the “you must be this tall to ride this ride” criterion? Include educational topics in the larger Help file—such as tutorials and overviews like “Principles of Network Security.” Just do not include links to such extraneous information in the task-support cluster—or include just a single link to the top-level topic. The point is to avoid the inevitable link farm that results if you try to provide links to all conceptually related topics. Such over-linking makes a Help system unnecessarily complex and encourages users to read about functionality when they would be better off back in the user interface actually doing something.

Defining Iterations

Let’s review the process for this iterative approach to Help:

1. Identify the pages that need context-sensitive Help.
2. For each of the pages the Help system supports, define a task-support cluster of Help topics.
3. Stub the file structure.
4. Write the task topics first.
5. Flesh out the clusters with the conceptual and reference topics.
6. Identify and write background and overview topics.

Your first iteration of the Help for early quality assurance (QA) testing might deliver just the user assistance structure you create in steps 1 through 3. As I mentioned earlier, because my company uses a topic mapping tool, Task Modeler, it is very easy for us to graphically design the structure of our task-support clusters and create stubbed XML files. Our DITA editor can easily transform those XML files into a Help file with navigation. So, with just our architectural design work and very little information development work, we can deliver a skeletal file to QA, who can then validate the navigational integrity between the user interface and the Help as well as among Help topics.

However, you would probably want your initial iteration of Help to be more complete and perhaps include the content for the task topics as well. That would allow QA to use the Help topics as test scripts—that is, QA can follow the documented procedures in the Help tasks and verify that the user interface behaves as described. A good first iteration, therefore, is one that includes steps 1 through 4.

Later iterations of the Help can flesh out the keystone concepts, references, and deep concepts within the task-support clusters. Subject-matter experts can review the content of these topics independently, because there is no need to verify them against the working user interface, as reviewers must do with tasks.

Even later iterations of the Help can develop basic conceptual topics such as overviews, broad background topics, and general support topics that you create to help users who come to the application “not tall enough to ride the ride.” Instead of supporting specific tasks—read to do—such topics are more educational in scope—read to learn. You can also develop advanced conceptual and reference topics in these later iterations to support advanced users.

As you can see, you can shape an iteration strategy around the functionality dimension—for example, “The Help we deliver on such-and-such a date will cover functions A through F,” as well as along a degree of completeness dimension, “...and cover just the task-support clusters, with only the task topics fleshed out.”

A typical iterative strategy could look like this:

Milestone	User Assistance Iteration
Code to QA	Task-support clusters stubbed, with task topics completed
Beta	Task-support clusters fully developed
General Availability	Overviews and educational topics completed

You can describe this iterative approach to design and development using an anatomical metaphor. Your first iteration is a neuro-skeletal build. You are laying out the framework and interconnections—hypertext links. The next iterations are the muscular builds. You are fleshing out the core-value topics that do the heavy lifting of the user assistance. Later iterations are the organic builds—adding the skin and final components that make it a fully viable entity.

Benefits of an Iterative Approach

The benefits of the approach I have described in this article are two-fold. This approach encourages the development of user assistance that is more relevant to users’ needs. Furthermore, it provides a development approach that lets user assistance authors connect with the product development and testing lifecycle sooner. In summary:

• The task-support cluster approach creates a strong user-centered, task-focused user assistance architecture. In effect, each cluster serves as an information express lane for users who have specific information requirements that their immediate tasks shape.
• The modularity and self-containment of the clusters help prevent users from getting lost in the Help. Many user assistance authors over-link their topics. Thinking about Help navigation in terms like “Oh, if a user is reading about x, she would probably also be interested in y,” gets replaced with this: “The user who came here was doing x; let’s deal with that and get her back into the application, not other topics in the Help.”
• The linking of the clusters to specific application pages and the emphasis on initial development of task topics allow early releases of Help files that can have immediate value in QA testing.