How to Write Readable Use Cases

Being a use case expert has less to do with drawing stick men and ovals than it has to do with writing. Creating use cases is, at its heart, a form of writing. A good use case, like good writing, is easy to read. But good writing is not easy writing. In fact, the opposite is usually true.

The building block of a use case is the step. A use case is made up of all the steps an actor takes to get something done with the system. To write a good use case, we need to write good steps. So what makes a good step?

Use case writing is a bit like story telling. Seriously. We're telling our readers a story about one way an actor will use the system we're specifying. For the story to be readable, it needs to be well-paced. And pace is controlled by the steps in the use case. Each step should be neither too detailed (fine-grained) nor vague (coarse-grained).

Fine-Grained Steps

First, there is the issue of fine-grained steps. Early in a project, when my enthusiasm is still high, I'm hungry for the sense of progress that comes from capturing lots of detail. So I write very detailed steps, like the ones in this Find Reservation use case:

Detailed use case template

Writing with too much detail brings two major problems: 1) I'm constantly rewriting because small details change more frequently than bigger concepts and 2) the pace of the use case becomes tedious and slow. It's nearly impossible to keep the main flow down to six-to-ten steps. Most importantly, the reader has to work harder in order to fully understand the entire use case.

Coarse-Grained Steps

Next, there is the problem of steps that are too vague. Later in the a project, when my enthusiasm wanes and the focus turns to hitting a deadline, I slip into writing vague, high-level steps, like these:

Vague use case template

Vague steps reduce the amount of work for me, the use case writer. But these steps leave out facts that are important to my readers - especially developers and testers.

Just Right Steps

So what's the key to writing steps that are neither too detailed nor too course, but just right? Make each step describe one of two things:

  • What action the actor needs to take, or
  • What work the system is doing for the actor (write the what, not the how)

Write each step as a simple declarative sentence beginning with either the name of the actor or the system (that is, ActorName verb object or The System verb object). I then wind up with a use case that reads like this:

clear use case template

Following these guidelines, the story behind each use case moves quickly enough to be readable without missing important detail.