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.



Comments (3)

10/22/2008 1:50:20 PM #

Doug

So assuming that the information about the grid being sortable by name, date or hotel is useful (part of the too much detail version, but not in the just-right version), where should it be recorded?  A requirement attached to the use case? An expected result of the testing procedure? Nowhere? (Leave it to the UI designer.) Or doesn't it matter, just as long as the information gets communicated to the right people.

Doug United States


11/12/2008 11:44:18 AM #

Matt Terski

Regarding specifying grid sort criteria: It depends on how you're running your project. Specifically, it depends on to what extend you are documenting UI details. Which, in turn, probably depends on how your team is organized.

If the team is highly distributed, it may be necessary to capture lots of details about the UI. Don't put these in your steps. Either write these as individual requirements and attach them to the use case - or create a screen specification/mockup that hold such detail and reference that document from the use case.

If the team is co-located and working in a more agile mode, it might make more economical to simply create the screen, review it with stakeholders, and modify as needed.

Matt Terski United States


6/15/2009 10:27:53 AM #

Leadership Theory

"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)"

- Ah that was my mistake, I wasn't conveying the what, I was writing about the 'how'.

Leadership Theory United Kingdom


Comments are closed