Five Tips for Writing Use Cases
When we talk about writing use cases, we’re usually talking about writing its main success scenario – the most important part. It describes the interaction as the actor completes the use case's objective. Here are five ways to write a solid main success scenario:
1. Make each step show an action
A use case is a story. Stories that don’t move forward are boring (and hard to read). So, each step in the use case should show some progress towards the eventual goal.
While each step is unique, you'll really only write five kinds of steps:
- The actor provides information
- The actor provides information
- The actor makes a choice
- The system provides information
- The system asks for information
- The system does some work
Each steps should show what the actor does or gets. Making each step an action will keep your use case lively and readable.
2. Keep it between six and ten steps
When a use case is 6-10 steps long, your reader can absorb and understand it in a minute or two.
If it's much longer, it will be harder to understand. It’s commonly said that we humans can keep only 5-9 items in our short term memory. If your use case is much longer than 10 steps, reconsider the goal of the use case. Ask yourself how the actor completes that goal and see if you can break it in two.
If a use case is much shorter than 6 steps, it's probably too fine grained and the reader won't see the bigger picture. You’ll end up with a large number of small use cases, which is harder to manage. Ask yourself why the actor is completing the use case to find the higher-level goal.
3. Avoid if statements
When writing a step that describes your system checking something, you might be tempted to use an if statement:
If the applicant's credit score is valid, the systems presents a confirmation number.
Don't do this. You'll probably need an else statement to go along with that if statement. The system you're working on is probably complex. So you won't be able to capture all of its complexities with a single if statement. You might need to nest another if statement inside of that first one. Before you know it, you'll be trying to code your system with a use case. That won't work.
Instead, write validation steps in the affirmative. Use verbs like validate and verify.
The system verifies the applicant's credit score is valid. The system presents a confirmation number.
This moves the use case forward in when everything is going right. You might ask, “What if the credit score isn’t valid?” The proper way to capture those alternate cases is with an extension. We'll cover those later.
4. Forget the UI (for now)
When writing use case steps, exclude details about button clicks, text boxes, checkboxes, etc. Don't get hung up on describing the user interface. This will slow you down and have you updating your use case for every minor UI tweak. A screen mockup or wireframe is a great place to describe a user interface. A use case’s main success scenario is not.
Here’s an example of what NOT to do:
- The customer enters a routing number into the routing number textbox.
- The customer enters an account number into the account number textbox.
- The customer clicks the Add Payment Account button.
- The system shows a calendar with available payment dates.
Instead, describe the intent of what happens in the step. Is the system showing something important? Is the system prompting for an answer? Is the user making a selection? Write it in a way that frees you from the UI. After you’ve captured this flow, you can then define and refine the UI again and again without having to update the use case.
Rewriting the steps above, but focusing on intent might result in something like this:
- The customer enters the payment account information.
- The system shows possible payment dates.
- The customer selects a payment date.
These steps will require much less maintenance as we finalize the user interface.
5. Put formulas and rules elsewhere
When writing use case steps, you'll encounter business rules, formulas, and other constraints that govern the behavior of your system. It's important to capture these things, but not right in the step of a use case. There are a few reasons for this:
- These rules, formulas, and constraints probably apply to more than one use case step.
- You'll want to define and maintain these in just one place.
- At some point, you'll want to see a list of these things on their own.
You would NOT want to write a use case step like this:
The customer selects a payment date. Dates for automatic recurring payments must fall between 10 days prior to the due date and the due date itself.
Instead, write something like:
The customer selects a valid recurring payment date.
And then maintain the description of a valid recurring payment date as a separate business rule. So go ahead and maintain a list of business rules, data definitions, and the like. But do it outside of your use cases.
Next time, we’ll cover how to handle alternate or exceptional behavior (e.g. if statements) in your use cases.
