Writing Effective Use Cases Overview of Alistairs approach

Writing Effective Use Cases Overview of Alistair’s approach

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) “Place an order” (level of goal [summary, user, subfunction]) (User goal / Clerk) (primary actor) Main scenario: 1. Clerk identifies customer, item and quantity. 2. System accepts and queues the order. (action steps: full sentences showing who takes the action! 3 - 9 steps long. ) (condition causing different actions) Extensions: *a. Network goes down: (action step(s) 1 a. Low credit & Customer is ‘Preferred’: handling those conditions) System gives them credit anyway. 1 b. Low credit & not ‘Preferred’ customer: Clerk accepts only prepayment. 2 a. Low on stock: Customer accepts rain-check: Clerk reduces order to available stock level. 2

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. 3

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 ! 4

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. 5

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. 6

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. 7

Stakeholders and Actors • Stakeholder 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 8

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). 9

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: 1. 2. 3. 4. 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. 10

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 11

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

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

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

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) Iteration D (10 more use cases) (10 use cases) E 15 E E *Show* UCs, system to users/sponsors, get feedback! Adjust your working habits *each iteration* to fit your particular situation! Use close communication! E

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 ! 16

Good use cases 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 Agile) 17 (more common)

Scope and UC level 18 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

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. 1. Customer runs ATM card through the card reader 2. ATM reads the bank ID and account number 3. ATM asks customer whether to proceed in Spanish or English 4. Customer selects English 5. ATM asks for PIN number and to press Enter 6. Customer enters PIN number, presses Enter 7. ATM presents list of activities for the Customer to perform. 8. Customer selects “withdraw cash” 9. ATM asks customer to say how much to withdraw, in multiple of 5$, press Enter 10. Customer enters an amount, a multiple of 5$, presses Enter 11. ATM notifies maon banking system of customer account, amount being withdrawn 12. Main banking system accepts the withdrawal, tells ATM new balance 13. ATM delivers the cash 14. ATM asks whether customer would like a receipt 15. Customer replies yes 16. ATM issues receipt showing new balance 19

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

Use case: Login This Use Case describes the process by which users log in to the orderprocessing system. It also sets up access permissions for various categories of users Flow of Events: Basic Path: 21 1. The use case starts when the user starts the application. 2. The system will display the Login screen. 3. The user enters a username and password 4. The system will verify the information 5. The system will set access permissions 6. The system will display the Main screen 7. The user will select a function. 9. If the user selects Place Order, Use Place Order 10. If the user selects Return Product, Use Return Product 11. If the user selects Cancel Order, Use Cancel Order 12. If the user selects Get Status on Order, Use Get Status 13. If the user selects Send Catalog, Use Send Catalog 14. If the user selects Register Complaint, Use Register Complaint 15. If the user selects Run Sales Report, Use Run Sales Report. end if 16. The user will select a function End loop 17. The use case ends

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. 22

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 23

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

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

Summary of Use Cases • User’s goal level - Text - 3 -9 -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 26

Agile Use Cases Alistair Cockburn Humans and Technology acockburn@aol. com http: //Alistair. Cockburn. us 27