Use Cases for User Assistance Writers

Process Overview

The process of using use cases to design and develop user assistance topics is simple:

1. For a given set of functionality, create a use case diagram that identifies the major user tasks.
2. Based on the use case diagram, create an initial list of task topics your documentation team needs to write.
3. Create a table of contents (TOC) or hierarchical architecture that shows how you’ll organize the task topics. Identify any obvious conceptual or reference topics users need and include those as well. (This step can also help identify missing use cases.)
4. Document each of the task topics as a use case description—minus the procedural steps. (I’ll talk more about this later in this column.)
5. As the user interface stabilizes, add the procedural steps to each of the task topics.
6. Before a functional block or iteration goes to testing, build the related portion of the user assistance and integrate it with the code block to be tested.

Next, I’ll focus on the documentation this process produces.

Use Case Diagrams

A use case diagram is a UML (Unified Modeling Language) illustration that identifies the key actors, the system of interest, the individual tasks, and the relationships among the tasks themselves—such as uses or extends. As Figure 1 shows, UML uses stick figures for actors, ovals for use cases, and lines for relationships.

One of the strengths of use case diagrams is that they are very high level. We constructed the one shown in Figure 1 by analyzing the product requirements document, then working with our usability team members, who had already done some preliminary wireframing. The diagram provided a good starting point for getting consensus among the stakeholders as to: Is this is what we intend for users to be able to do with this module?

To create use case diagrams, you can:

• Use the UML use case diagram stencil in Visio.
• Download free use case modeling software such as the Essential Modeler.

Use Case Descriptions

Once you get initial agreement among the stakeholders that the use case diagram is a fairly accurate and inclusive inventory of what users can do with the system, you can start documenting use cases—represented by each oval in the use case diagram—with task topics. At this stage, you might find that some use cases expand into multiple tasks, while others combine into a single task. Don’t be reluctant to redefine the map as the landscape starts becoming clearer.

As my team went through the tutorial I mentioned earlier, we noted a striking similarity between the elements it identified as being part of a use case description and the components a DITA task topic specifies. Table 1 shows a comparison of their elements and DITA components. You do not have to use DITA to structure your task topics in this way. Just create an appropriate template in whatever authoring tool you use.

Table 1—Comparison of use case elements and DITA task topic components

Use Case Element	DITA Topic Component	Description
Name	<title>	The name of a use case starts with an active verb and indicates a successful outcome that is of value to the actor. This is a good convention for naming task topics as well. Use cases tend to use the imperative form—such as Print a Report. According to our style guide, we name tasks using gerunds, so in the task topic, we would rename that case Printing a Report.
Brief Description	<shortdesc>	A DITA short description is usually less than 25 words and centers on the user goal or outcome of the task. In a use case description, this is exactly what the brief description does.
Precondition	<prereq>	This element describes what conditions must be in place before a user can perform the task.
Business Trigger	<context>	This is perhaps the most important element—though often neglected—and answers this question: When or why would a user do the task? This is an area where technical communicators can add great value to the overall design effort, because product developers sometimes focus on what action initiates a use case, while writers tend to probe more for the user’s motivation. For example, in a developer’s mind, an ATM use case starts with the user inserting his bank card; for a writer, it starts with the user’s needing cash.
Basic Flow	<steps>	In classic use case descriptions, this is the description of the transactional interplay between actor and system—as in (1) User does this; (2) System does that in response. If you’re using the use case approach mainly to design the user assistance—rather than to define the functional requirements—you can leave this section blank initially, then fill it in later with traditional step-by-step instructions once the user interface design settles down.
Post Condition	<result>	This element describes the end state of a procedure or what constitutes a successfully completed task in user terms—for example, the impact the procedure has on the user or the system or how to validate that a user performed the task correctly.

Initially, you can ignore the Basic Flow section—the <steps> block of the DITA task topic. You can document those once the designers and developers decide how the actual user interface will look and behave. The elements that come before and after the steps represent contextual elements that are largely independent of how the user interface actually lets users perform the task. I refer to these as the contextual elements to differentiate them from the behavioral steps.

Figure 2 shows an empty task topic in our DITA editor. An extension lets us automatically generate headings for the topics, as shown in Figure 2. Headings are not a DITA requirement, but they provide a consistent aid for readers and serve as reminders to the writer of the purpose of each element. These headings help you relate the sections shown in Figure 3 to their respective DITA elements.

Figure 3 shows a task topic in which I’ve grayed out the procedural steps to emphasize only the contextual elements. You can immediately see that the procedural steps are a relatively small portion of the task topic. The contextual elements account for the majority of the wordsmithing effort, both in terms of the amount of the writing and the stylistic decisions a writer would have to make. In contrast, the steps apply a highly formulaic style and are, therefore, straightforward to compose and edit alike. Most importantly, a writer does not need to know the actual steps to describe the contextual elements, which lets the writer get an early jump on writing the documentation. And because the writer is not initially distracted by documenting the steps, he or she can focus on answering decision-support questions—such as Why would a user do this? and When would a user do this?

And lastly, by getting involved early, before the user interface elements are in place, the information developer has a greater opportunity to shape the user experience by providing embedded user assistance solutions such as improved labels or interactive user assistance for user interface elements.

Conclusion

Use cases aren’t just useful tools for defining functional requirements. They can be a useful design tool for writers of user assistance. Not only do they focus on user goals and contexts, they let writers get started on final documentation before the product team has designed and developed the user interface. And finally, they let you create design documentation within the production tool, while you are producing content that persists into the final user assistance deliverable.