Creating a Use-Case Specification

A use case is one way of using the system. You identify the actors (the users of the system) and their use cases—placing them on a use-case diagram—in order to understand and organize your thoughts about the system, and as a useful way to organize the system’s requirements, analysis, design, and potential artifacts (documents, diagrams, and so on).

You can also consider a use case as a behavior that the system offers to the actors to help meet the actors’ goals. (For more on identifying actors and their use cases, and drawing them in use-case diagrams, see Chapter 8.)

UML tells you to draw use cases as named ovals, and to connect them to their actors (stick figures and boxes), but it doesn’t say much about how to supply details of how the system performs behaviors needed to meet the actors’ goals. Though use-case diagrams are helpful, without more information on how the system is to do this work, your development effort will stall. So you have to supply information on how the use case is to work—and put that information somewhere. Where? Somewhere close by and available when you need it, but not anywhere that clutters up the simplicity and effectiveness of your use-case diagrams. Figuratively we place these details inside the use case—not on the diagram, but behind the scenes. Often a textual document or form is the place to put these details; it may be reached (perhaps by hyperlinking) easily from the use-case oval.

This set of needed details placed inside a use case is sometimes called the use-case specification because you use it to specify (spell out in detail) how the system behaves when triggered by actors to meet their goal(s). (The format of the specification isn’t standardized in the industry—each development organization develops or modifies its own standard—but we’ve based the discussion that follows on the common features of the most popular approaches.)

Filling in this specification isn’t difficult if you step through the following tasks:

Identify and name your use case.

See Chapter 8 for more on this process.
Draw a diagram indicating the use case, as well as its primary (triggering) and secondary actors.

See Chapter 8 for more on drawing use-case diagrams.
Describe the use case briefly.

Give a sentence outlining the purpose of the use case.
Narrate the story of what happens in this use case.

The use-case narration should be a written story. Usually it starts with the phrase, “This use case starts when the actor <does something> . . .” and then describes what the actor and system do in the normal course of events. Often this description takes the form of alternating steps: The actor does this, and then the system does that, and so on, until the story ends with: “This use case ends when the system <does something> and <the actor’s goal> <is satisfied>.” If there are some major plot variations to the story (that is, alternate paths the use case might take), you should include them in the narration as well. You don’t have to be exhaustively complete—and certainly don’t be formal. Go for a few paragraphs that get the idea across.
Describe the main course (sometimes called the main flow) of events in your use case.

When you and your customers are satisfied with your narration, you can take the main story—the typical interchange of events—and capture this flow of events (what the actor does and then what the system does, and so forth) more formally. Later in this chapter, we give various popular techniques for capturing a flow of events.
Define appropriate pre- and postconditions for this flow of events.

As part of making the flow of events more formal and precise, we specify the conditions that must be true to enable this version of the story to occur—the preconditions. We also specify the conditions that will be true after this flow of events finishes—the postconditions.
Identify alternative, error, and exception scenarios.

Now we look at the alternate plot lines we indicated in the narration. We identify all the alternative paths, possible errors (and their consequences), and exceptional situations that the use case might encounter.
Describe each scenario’s alternative course with a flow of events, adding pre- and postconditions.

Using the same techniques used in Step 5 (to describe the flow of events for the main course), describe each alternate course identified in Step 7. Then identify the pre- and postconditions, as in Step 6.
Add to the use case any requirements that must be obeyed, or any implementation notes.

Document any usual business rules and data validations that the use case must enforce. Capture any guidelines on design and implementation that might be helpful.

Remember, every use case must have a specification constructed. How much of the specification you ought to fill out depends on the formality of your project and where you are in your project.