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
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.
The process of using use cases to design and develop user assistance topics is simple:
- For a given set of functionality, create a use case diagram that identifies the major user tasks.
- Based on the use case diagram, create an initial list of task topics your documentation team needs to write.
- 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.)
- 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.)
- As the user interface stabilizes, add the procedural steps to each of the task topics.
- 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.