1. Writing Effective Use Cases
Overview of Alistair’s approach

2. Robert Martin: “It shouldn’t take longer than 15 minutes to teach someone how to write a use case!”
Use case: Text describing scenarios of user succeeding or failing to achieve goal.
(goal of primary actory)
(level of goal [summary, user, subfunction])
“Place an order” (User goal / Clerk)
Main scenario:
1. Clerk identifies customer, item and quantity.
2. System accepts and queues the order.
Extensions:
*a. Network goes down:
1a. Low credit & Customer is ‘Preferred’:
System gives them credit anyway.
1b. Low credit & not ‘Preferred’ customer:
Clerk accepts only prepayment.
2a. Low on stock: Customer accepts rain-check:
Clerk reduces order to available stock level.
(primary actor)
(action steps: full sentences showing who takes the action!
3 - 9 steps long.)
(condition causing different actions)
(action step(s) handling those conditions)
Why was this important?
It clarified our vocabulary and
It included all the parts we needed to function
Discuss other ways to write use cases
narrative
formal scripts

3. Use cases have strong & weak points (as anything)
1. Use cases hold functional requirements in an easy-to-read text format
2. They make a good framework for non-functional requirements & project scheduling.
3. Use cases show only the Functional req’ts.
4. Design is not done only in use case units.

4. Use cases do not collect formulas, state, cardinality, performance, uptime, ...
Examples:
1. Order cost = order item costs * 1.06 tax
2. Promotions may not run longer than 6 months.
3. Customers only become Preferred after 1 year.
4. A customer has one and only one sales contact.
5. Response time is less than 2 seconds.
6. Uptime requirement is 99.8%.
7. Number of simultaneous users will be 200 max.
Capture those in any form available,
*somewhere* in your requirements files !

5. Requirements and use cases
If you are writing use cases as requirements, keep two things in mind:
They really are requirements. You shouldn’t have to convert them into some other form of behavioral requirements. Properly written, they accurately detail what the system must do.
They are not all of the requirements. They don’t detail external interfaces, data formats, business rules, and complex formulae. They constitute only a fraction (perhaps a third) of all the requirements you need to collect – a very important fraction but a fraction nonetheless.

6. When use cases add value – first value
When UC-s are named as user goals that the system will support,
and are collected into a list. (scope, system’s purpose in life)
This list of goals will be examined by user representatives, executives, expert developers, and project managers, who will estimate the cost and complexity of the system starting from it.
The list is a framework to which to attach complexity, cost, timing, and status measures.

7. When use cases add value – second value
The use case writers brainstorm all the things that could go wrong in the successful scenario, list them, and begin documenting how the system should respond.
Often a new stakeholder, system, goal, or business rule is discovered while documenting the failure handling.
Without descrete use case steps and failure brainstorming, many error conditions go undetected until some programmer discovers them while typing a code fragment.
People who write one-paragraph use cases save lot of time by writing so little and already reap one of the benefits of use cases.

8. Stakeholders and Actors
Someone or something that has vested interest in the behaviour of the use case.
Actor:
is anything having behaviour
Primary Actor
is the stakeholder that calls on the system to deliver one of its services. The actor, who triggers the use case.
Secondary (Supporting) Actor
an external actor that provides a service to the SUD
Internal Actor

9. Exercise
You have been hired to create requirements document for a new ATM. Decide whether each item in the following list is:
a stakeholder,
a primary actor,
a supporting actor,
the system under design,
or not an actor at all (or a multiple of the above).

10. Manage your energy
Energy of writing use cases is divided into four stages of precision, according to the amount of energy required and the value of pausing after each stage:
Actors and goals
Use case brief or main success scenario
Failure conditions
Failure handling
Most of projects are short on time and energy. Managing the precision level to which you work should therefore be a project priority.

11. Use cases provide 4 values to the project at different times:
1. The list of goal names provides executives:
Shortest summary of what system will contribute
Project planning skeleton (priorities & timing)
2. The main success scenario provides all:
Agreement as to the system’s responsibilities
3. The extension conditions provide programmers:
List of things programmers have to watch for
List of things analysts have to investigate
4. The extension handling steps provide dev’t team:
Record of (tricky) business policy decisions

12. Goals make a good structure on which to hang requirements & project details.
Project planning capitalizes on goal structure:
Useable Releases.
Priorities,
Schedule, staffing
Name P. Actor Pr. Diff. Release
Update customer Customer high med 1
Scan products Customer high high 1
Generate invoice Finance high high 3
Funds transfer Finance med high 4
(Note: spreadsheets are perfect for this!)

13. Goals make a good structure on which to hang requirements & project details.
Project planning capitalizes on goal structure:
Useable Releases.
Priorities,
Schedule, staffing
Actor
Task-level Goal
Business need
Technical
Difficulty
Priority
UC#
Any
Check on requests
Topp
Complex 1 2
Buyer
Change vendor contacts
Medium
Simple 3
Requestor
Initiate an request 5
Approver
Complete request for submission
High 11
Cancel a request
low 4 17
Authorizer
Validate Approver's signature
Hard 14

14. The hard parts about use cases is not typing, but thinking and agreeing.
Total time
~ 3 days construction
~ 2 hours typing
2-3/4 days spent thinking, arguing (over policy).
1. Is each step correct?
2. Are there any system responsibilities between steps?
3. Are there any outside systems this system should use?
4. Are there any other stakeholders whose interests we missed?
5. Did we catch every extension condition?
(The programmers will (maybe))

15. Project horizon -> all use case briefs or casual Iteration horizon -> full use case, just-in-time D
(all UCs, ultra-light content, estimation purposes)
Full Project
(just-in-time, complete)
(just-in-time, complete)
(just-in-time, complete)
Iteration
Iteration
Iteration D D
(10 use cases)
(10 more use cases)
(10 more use cases) E E E E E E
*Show* UCs, system to users/sponsors, get feedback! Adjust your working habits *each iteration* to fit your particular situation! Use close communication!

16. Don’t try to teach a tutorial on the subject domain within the use cases!
In any text, receiver must always jump a gap.
Experts jump larger gaps
Novices jump smaller gaps.
To teach a domain, you need a textbook, not use cases.
Textbooks use smaller gaps.
Think of use cases as “documenting decisions”, not “teaching the domain.”
Target the gap for the people: “sufficient” communication with a “small-enough”gap.
More experienced people need less writing !

17. Good use cases are aren’t
Text
No GUI
No data formats
3 - 9 steps in main scenario (complete UC <2 pages)
Easy to read
At user’s goal level
Record of decisions made
UML use case diagrams
describing the GUI
describing data formats
multiple-page main scenario
complicated to read
at program-feature level
tutorial on the domain
Use cases *can be* written --
just-in-time --or-- all up front
in (usable) increments --or-- each to completion
(more common)
(more Agile)

18. Scope and UC level Design scope Goal level Organization (black-box)
(cloud) Very High summary
Organization (white-box)
(kite) Summary
System (black box)
(sea) User-goal
System (white box)
(fish) Subfunction
Component
Too low

19. Here is the interface detail description for withdrawing cash from an ATM. Sending out 100 use cases like this will make for some unhappy readers.
Customer runs ATM card through the card reader
ATM reads the bank ID and account number
ATM asks customer whether to proceed in Spanish or English
Customer selects English
ATM asks for PIN number and to press Enter
Customer enters PIN number, presses Enter
ATM presents list of activities for the Customer to perform.
Customer selects “withdraw cash”
ATM asks customer to say how much to withdraw, in multiple of 5$, press Enter
Customer enters an amount, a multiple of 5$, presses Enter
ATM notifies maon banking system of customer account, amount being withdrawn
Main banking system accepts the withdrawal, tells ATM new balance
ATM delivers the cash
ATM asks whether customer would like a receipt
Customer replies yes
ATM issues receipt showing new balance

20. Answer Customer runs ATM card through the card reader
ATM reads the bank ID and account number from the card, validates them with the main computer
Customer enters PIN.
ATM validates PIN
Customer selects FASTCASH and withdrawal amount, a multiple of 5$
ATM notifies main banking system of customer account, amount being withdrawn, and receives acknowledgement plus the new balance
ATM delivers the cash, card, and a receipt showing the new balance
ATM logs the transaction <- don’t forget RISK Department, who is one of the Stakeholders!

21. Use case: Login This Use Case describes the process by which users log in to the order-processing system. It also sets up access permissions for various categories of users
Flow of Events:
Basic Path:
The use case starts when the user starts the application.
The system will display the Login screen.
The user enters a username and password
The system will verify the information
The system will set access permissions
The system will display the Main screen
The user will select a function.
If the user selects Place Order, Use Place Order
If the user selects Return Product, Use Return Product
If the user selects Cancel Order, Use Cancel Order
If the user selects Get Status on Order, Use Get Status
If the user selects Send Catalog, Use Send Catalog
If the user selects Register Complaint, Use Register Complaint
If the user selects Run Sales Report, Use Run Sales Report.
end if
The user will select a function
End loop
The use case ends

22. Answer There are three kinds of mistakes:
Use case is not about Logging in regardless of what the use case name and description say. The first six steps are about logging in, but that is at a different goal level entirely and should be separated out. Once we do that, we notice that the user logs into this sytem but never logs out!
While the user does not select Exit loop, end if, and end loop are programmes constructs that will not make sense to the users reviewing the use case. The steps describe the user interface design. All of these should be fixed.
The use case starts when… and The use case ends when… are stylistic conventions suggested by some teachers. Most people naturally assume that the use case starts with step 1 and ends when the writing stops.

23. Answer - 2
The other style to note is the phrasing, User … then Use Place Order. The “use” in that phrase refers to the includes relation of UML. More easy to read would be places the order
In the end, we find two use cases to pull apart: the kite use case, Use the Order Processing System, and the subfunction, Log In

24. Answer - 3 Use case: Use the Order Processing System
Main Success Scenario:
User logs in.
System presents the available functions. User selects and does one of: Place order Cancel Order Get Status Send Catalog Register Complaint Run Sales Report
This repeats until the user selects to exit.
System logs user out when user selects to exit.

25. Possible ways. There are many
IBM/Rational way
2a. Invalid PIN:
ATM notifies Customer. Use Case resumes at basic flow point 3
2b. Invalid PIN more than retry limit:
ATM notifies customer and keeps the card. Use Case ends.
Alistair suggestion:
2a. Invalid PIN and retries allowed:
1. ATM notifies Customer
2. Customer reenters PIN
2b. Invalid PIN and retry limit reached:
1. ATM notifies Customer and keeps card.

26. Summary of Use Cases
User’s goal level - Text step main scenario - No GUI - No data formats - Easy to read - Record of decisions made (not a tutorial)
Write briefs and casuals to estimate & plan project Write full use cases just-in-time per iteration
Just-in-time = extension-handling decisions made before the programmer gets around to asking for them.
Spreadsheets good for briefs, planning activities. Focus on communicating, not filling templates
Develop requirements iteratively. Plan review meetings. Review UC-s with stakeholders, testers, developers

27. Agile Use Cases Alistair Cockburn Humans and Technology