You are writing the steps of a scenario as LeveledSteps(173).
Both readers and developers get confused about a system's behavior if it is not clear which actor has responsibility for performing a step, and is trying to accomplish in that step.
Some time ago I was visiting friends who have young children. Their seven-year-old son was trying to tell me about a movie that he had just seen.
“It was so cool, these guys search for this monster that is sinking ships, and well they find it, only it’s a submarine. They get captured and travel underwater in the submarine. There is this guy and he’s really fascinated by the submarine and the submarine captain is this ex prisoner guy and he’s got an attitude and he’s always mixing it up with this other guy. And then there is this giant squid that nearly eats him, but the other guy harpoons the squid
If I had never seen Disney’s version of Jules Verne’s 20,000 Leagues Under the Sea, I would have had a lot of trouble following this synopsis. I would have been confused as to which
“guy” was fascinated by the submarine, who had the attitude, and who saved whom when the Nautilus was attacked by the giant squid.
Writing quality use cases is hard work and it takes a lot of mental energy to create good prose. Often, people have trouble writing PreciseAndReadable(152) use cases. Non-programmers tend to write ambiguous steps and miss the meaningful details the developers need to know. Programmers, on the other hand, tend to generously incorporate both design and technology details in their use cases, making them too hard for the non-programmers to understand. Often, programmers are told to write the use cases that they themselves will implement, leading them to write entirely from the system's perspective, leaving out what the other actors will do.
The developers need to know clearly what they are to implement, at what moments the system should wait for input, and when the system should take the initiative. Otherwise, they are left to make their own assumptions about these issues, or spend time tracking down details they should already have. The cost of miscommunication is high, so we aim to write use cases that are general enough for all of the stakeholders to follow, yet precise enough for the developers to use when building the system (PreciseAndReadable(152)).
Therefore:
Write each step to clearly show which actor is performing the action, and what that actor will accomplish.
Minimize your writing effort by using a simple format for each step. We recommend a clear sentence with straightforward grammar: actor, verb, direct object, and prepositional phrase.
"User enters name and address," or "System notifies user of results." When the actor is visible in each step then it is clear to both the reviewers and the developers which actor must perform the step. This reduces ambiguity and helps protect the project from the problems that arise from miscommunication.
Use active verbs in the present tense to describe how an actor advances towards their goal (ForwardProgress(164)). Each step, except those at the lowest detail level, should address a lower level CompleteSingleGoal(132), so that if necessary, you can create an EverUnfoldingStory(117) by converting the step’s verb phrase into a lower-level use case.
The Actorless ATM
Having programmers write their own use cases often results in system-oriented scenarios such as:
5. Issue the cash and update the account.
6. Reset the system.
Use Case 1-8 Use Case Horror: ATM Description without a VisibleActorIntent
While this scenario is clear to the writer, it leaves questions about what is the customer’s part in the transaction. The following, better version of this use case clearly shows what is the actor’s intent:
USE CASE 44: Withdraw Cash
Primary Actor: User – Account Holder Level: User Goal.
Main success scenario:
1. User inserts their ATM card. (versus Read the ATM card.)
2. System reads and validates the card information (versus Validate the card information.)
3. User selects transaction and enters transaction details (Versus Collect the transaction information.)
4. System validates transaction details (versus Validate the transaction details.) 5. User collects cash and withdraws card. (after all what happened to the User?)
6. System and updates the account and resets the system (versus Issue the cash, update the account. Reset the system.)
Use Case 1-9 Improving ATM Description with VisibleActorIntent.
This style clearly shows who is responsible for what action.
In a related style, some people like to write in the passive voice, again leaving out which actor
USE CASE 44: Withdraw Cash
3. The transaction information gets collected and validated.
4. The cash is issued, card returned, cash removed, account debited, screen reset.
Use Case 1-10 Use Case Horror: Description Written in Passive Voice.
Unfortunately, different actors initiate the actions. While the steps are leveled and show forward progress, it is not clear to anyone, other than the writer, who is responsible for doing what. They can only guess.
A final mistaken style of writing is to name many, even technology-specific, movements the user of the system will take:
Use Case 1-11 Use Case Horror: Description with Technology Specific Steps.
Here, we can improve the writing by combining the steps, making it TechnologyNeutral(177), and capturing the intent of the actor instead of the technology-specific movements:
USE CASE 42: Access ATM
Primary Actor: User – Account Holder Level: User Goal.
1. User enters name and address.
2. System presents User’s profile.
Use Case 1-12 Improved TechnologyNeutral ATM Use Case.
1.4 ForwardProgress(164)