Use Cases for User Assistance Writers

By Mike Hughes

Published: September 22, 2008

“Perhaps the true measure of a good idea is its persistence, even though folks are slow to pick up on it.”

Perhaps the true measure of a good idea is its persistence, even though folks are slow to pick up on it. SGML is a good example. It seemed like a great idea, but for a long time, had trouble getting traction in the general tool space. Then it started showing up at technical communication conferences wearing a name badge that said, “Hi, my name is DITA,” and suddenly, it’s a hit!

The same seems to apply to use cases. It’s hard to find anyone who disparages them, but those who use them are still a minority. In a previous life as a UX designer, I used use cases and developed a great respect for them. But it wasn’t until recently that I began using them to design user assistance. Why did it take me so long to get back to these reliable work horses of user-centered design?

The Benefits

As is often the case, it took a problem that needed solving to make me return to a useful approach I hadn’t followed for a while. The documentation team I belong to was feeling pressure to break out of the documentation whirlpool that is so typical of waterfall development cycles—we can’t document the user interface until it’s finished, and it’s not finished until the last minute before release. We also needed to align ourselves with a development process that was moving more and more toward an agile development cycle. So we decided to incorporate a use case methodology into our information design and development process to meet the following objectives:

  • Start information development earlier in the product development process.
  • Have testable information products earlier in the product development iterations.
  • Improve our focus on user context.
  • Maximize reuse of design documents in the production phase.

The first two objectives—starting information design early and having testable information products earlier—go hand in hand. We wanted the product’s development iterations that were going into testing to have the procedural Help topics in place. Not only would this help us validate the accuracy of the topics, it would give the testers a framework against which to test the user interface, because the Help would describe the ideal way in which the product was intended to work.

Our desire to improve our focus on user context came from our commitment to

  • de-emphasize behavioral Help—which tells a user to “click this” or “type that”
  • include more decision-support Help—along the lines of What’s a good value for this parameter? or When would I choose option A over option B?
  • maximize the reuse of design documentation in production—which would help us to accommodate increasing demands on our limited resources
“We were committed to reducing the amount of work we put into documents that did not find their way to the users—such as elaborate documentation plans or design documents.”

In an earlier column, “Hockey Sticks and User Assistance: Writing in Times of Resource Constraints,” I pointed out that, contrary to the mantra of Do more with less, the only thing you can do with less is less. So we were committed to reducing the amount of work we put into documents that did not find their way to the users—such as elaborate documentation plans or design documents. Any documentation we did for planning or design purposes had to convert quickly and easily into user documentation. The approach we decided to try was to create two types of design documents:

  • use case diagrams—A use case diagram provides an overview of a major set of functionality. Essentially, it is a visual master inventory of the tasks a user can do. This is our only throw-away design document—that is, the only design document users will not eventually see in some form.
  • use case descriptions—These are verbal descriptions of each task in the use case diagram. We document our use cases using DITA (Darwin Information Typing Architecture) task topics, so they can evolve into the actual user documentation. As I will show later in this column, the DITA task structure lends itself well to a use case methodology.

In this article, I won’t be able to provide a complete explanation of how to create such documents. But I suggest you refer to a free tutorial we used—“Specifying Functional Requirements With Use Cases—which will teach you everything you need to know in a short time. The rest of this column, therefore, concentrates on the overall process of using use cases to design and rapidly develop user assistance topics.

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

“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?

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?

Figure 1—Part of a UML use case diagram

UML use case diagram

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 with task topics.”

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 2—Elements of a task topic with dynamically generated headings

Elements of a task topic

Figure 3—A task topic with procedural steps grayed out

Task topic
“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.”

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.”

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.

1 Comment

Nice article, thank you. I am interested in both DITA and use cases, although I’m a novice at both. This article will help shape my approach to a new UA project I’m working on.

Regards, Owen

Join the Discussion

Asterisks (*) indicate required information.