Writing use cases as a means of capturing the behavioral requirements of software systems and business processes is a practice that is quickly gaining popularity. Use cases provide a beneficial means of project planning because they clearly show how people will ultimately use the system being designed. On the surface, use cases appear to be a straightforward and simple concept. Faced with the task of writing a set of use cases, however, practitioners must ask: "How exactly am I supposed to write use cases?" Because use cases are essentially prose essays, this question is not easily answered, and as a result, the task can become formidable.
In Writing Effective Use Cases, object technology expert Alistair Cockburn presents an up-to-date, practical guide to use case writing. The author borrows from his extensive experience in this realm, and expands on the classic treatments of use cases to provide software developers with a "nuts-and-bolts" tutorial for writing use cases. The book thoroughly covers introductory, intermediate, and advanced concepts, and is, therefore, appropriate for all knowledge levels. Illustrative writing examples of both good and bad use cases reinforce the author's instructions. In addition, the book contains helpful learning exercises--with answers--to illuminate the most important points.
Highlights of the book include:
With this book as your guide, you will learn the essential elements of use case writing, improve your use case writing skills, and be well on your way to employing use cases effectively for your next development project.
Download the sample pages (includes Chapter 3 and Index)
What Is a Use Case (More or Less)?
USE CASE 1. Buy Stocks over the Web.
USE CASE 2. Get Paid for Car Accident.
USE CASE 3. Register Arrival of a Box.
Your Use Case Is Not My Use Case.
USE CASE 4. Buy Something (Casual Version).
USE CASE 5. Buy Something (Fully Dressed Version).
Steve Adolph: “Discovering” Requirements in New Territory.
Requirements and Use Cases.
Use Cases as Project-Linking Structure.
Figure 1: The “Hub-and-Spoke” Model of Requirements.
When Use Cases Add Value.
Manage Your Energy.
Warm Up with a Usage Narrative.
Usage Narrative: Getting “Fast Cash”.
PART I. THE USE CASE BODY PARTS.2. The Use Case as a Contract for Behavior.
Interactions between Actors with Goals.
Actors Have Goals.
Figure 2: An Actor with a Goal Calls on the Responsibilities of Another.
Goals Can Fail.
Interactions Are Compound.
A Use Case Collects Scenarios.
Figure 3: Striped Trousers: Scenarios Succeed or Fail.
Figure 4: The Striped Trousers Showing Subgoals.
Contract between Stakeholders with Interests.
Figure 5: The Sud Serves the Primary Actor, Protecting Offstage Stakeholders.
The Graphical Model.
Figure 6: Actors and Stakeholders.
Figure 7: Behavior.
Figure 8: Use Case as Responsibility Invocation.
Figure 9: Interactions as Composite.3. Scope.
Table a Sample In/Out List.
The Actor-Goal List.
Table a Sample Actor-Goal List.
The Use Case Briefs.
Table Sample Use Case Briefs.
Figure 10: Design Scope Can Be Any Size.
Using Graphical Icons to Highlight the Design Scope.
Design Scope Examples.
USE CASE 6 Add New Service (Enterprise).
USE CASE 7 Add New Service (Acura).
Many Computers to One Application.
USE CASE 8 Enter and Update Requests (Joint System).
USE CASE 9 Add New Service (into Acura).
USE CASE 10 Note New Service Request (in BSSO).
USE CASE 11 Update Service Request (in BSSO).
USE CASE 12 Note Updated Request (in Acura).
Figure 11: Use Case Diagrams for Acura-BSSO.
Figure 12: A Combined Use Case Diagram for Acura-BSSO.
Nuts and Bolts Use Cases.
USE CASE 13 Serialize Access to a Resource.
USE CASE 14 Apply a Lock Conversion Policy.
USE CASE 15 Apply an Access Compatibility Policy.
USE CASE 16 Apply an Access Selection Policy.
USE CASE 17 Make Service Client Wait for Resource Access 49
The Outermost Use Cases.
Using the Scope-Defining Work Products.
Exercises.4. Stakeholders and Actors.
The Primary Actor.
Why Primary Actors Are Unimportant (and Important).
Actors versus Roles.
Characterizing the Primary Actors.
Table a Sample Actor Profile Table.
The System Under Discussion.
Internal Actors and White-Box Use Cases.
Exercises.5. Three Named Goal Levels.
User Goals (Blue, Sea-Level).
Figure 13: Use Case Levels.
Two Levels of Blue.
Summary Level (White, Cloud/ Kite).
USE CASE 18 Operate an Insurance Policy+.
The Outermost Use Cases Revisited.
Subfunctions (Indigo/Black, Underwater/Clam).
Summarizing Goal Levels.
Using Graphical Icons to Highlight Goal Levels.
Finding the Right Goal Level.
Finding the User's Goal.
Raising and Lowering Goal Levels.
Figure 14: Ask “Why” to Shift Levels.
A Longer Writing Sample: “Handle a Claim” at Several Levels.
USE CASE 19 Handle a Claim (Business).
USE CASE 20 Evaluate Work Comp Claim.
USE CASE 21 Handle a Claim (Systems) +.
USE CASE 22 Register a Loss.
USE CASE 23 Find a Whatever (Problem Statement).
Exercises.6. Preconditions, Triggers, and Guarantees.
Exercises.7. Scenarios and Steps.
The Main Success Scenario.
The Common Surrounding Structure.
The Scenario Body.
GUIDELINE 1: Use Simple Grammar.
GUIDELINE 2: Show Clearly “Who Has the Ball”.
GUIDELINE 3: Write from a Bird's Eye View.
GUIDELINE 4: Show the Process Moving Forward.
GUIDELINE 5: Show the Actor's Intent, Not the Movements.
GUIDELINE 6: Include a “Reasonable” Set of Actions.
Figure 15: A Transaction Has Four Parts.
GUIDELINE 7: “Validate,” Don't “Check Whether”.
GUIDELINE 8: Optionally Mention the Timing.
GUIDELINE 9: Idiom: “User Has System a Kick System B”.
GUIDELINE 10: Idiom: “Do Steps x-y Until Condition”.
To Number or Not to Number.
The Extension Conditions.
Brainstorm All Conceivable Failures and Alternative Courses.
GUIDELINE 11: Make the Condition Say What Was Detected.
Rationalize the Extensions List.
GUIDELINE 12: Indent Condition Handling.
Failures within Failures.
Creating a New Use Case from an Extension.
Exercises.9. Technology and Data Variations.
Figure 16: Technology Variations Using Specialization in UML.10. Linking Use Cases.
Sub Use Cases.
Extension Use Cases.
Figure 17: UML Diagram of Extension Use Cases.
When to Use Extension Use Cases.
Exercises.11. Use Case Formats.
Formats to Choose From.
USE CASE 24 Fully Dressed Use Case Template.
USE CASE 25 Actually Login (Casual Version).
Table 1 One-Column Table Format of a Use Case.
Table 1 Two-Column Table.
USE CASE 26 Register for Courses.
The UML Use Case Diagram.
Forces Affecting Use Case Writing Styles.
Standards for Five Project Types.
For Requirements Elicitation.
USE CASE 27 Elicitation Template—Oble a New Biscum.
For Business Process Modeling.
USE CASE 28 Business Process Template—Symp a Carstromming.
For Sizing the Requirements.
USE CASE 29 Sizing Template—Burble the Tramling.
For a Short, High-Pressure Project.
USE CASE 30 High-Pressure Template: Kree a Ranfath.
For Detailed Functional Requirements.
USE CASE 31 Use Case Name—Nathorize a Permion.
1Exercise.PART II. FREQUENTLY DISCUSSED TOPICS.
On Being Done.13. Scaling Up to Many Use Cases.
Say Less about Each One (Low-Precision Representation).
Create Clusters of Use Cases.14. CRUD and Parameterized Use Cases.
CRUD Use Cases.
USE CASE 32 Manage Reports.
USE CASE 33 Save Report.
Parameterized Use Cases.15. Business Process Modeling.
Modeling versus Designing.
Work from the Core Business.
Figure 18: Core Business Black Box.
Figure 19: New Business Design in White Box.
Work from Business Process to Technology.
Figure 20: New Business Design in White Box (Again).
Figure 21: New Business Process in Black-Box System Use Cases.
Work from Technology to Business Process.
Linking Business and System Use Cases.
Rusty Walters: Business Modeling and System Requirements.16. The Missing Requirements.
Precision in Data Requirements.
Cross-linking from Use Cases to Other Requirements.
Figure 22: “Hub-and-Spoke” Model of Requirements.17. Use Cases in the Overall Process.
Use Cases in Project Organization.
Organize by Use Case Titles.
Table 1 Sample Planning Table.
Handle Use Cases Crossing Releases.
Deliver Complete Scenarios.
Use Cases to Task or Feature Lists.
USE CASE 34 Capture Trade-In.
Table Work List for Capture Trade-In.
Use Cases to Design.
A Special Note to Object-Oriented Designers.
Use Cases to UI Design.
Use Cases to Test Cases.
USE CASE 35 Order Goods, Generate Invoice (Testing Example).
Table 1 Main Success Scenario Tests (Good Credit Risk).
Table 1 Main Success Scenario Tests (Bad Credit Risk).
The Actual Writing.
A Branch-and-Join Process.
Time Required per Use Case.
Collecting Use Cases from Large Groups.
Andy Kraus: Collecting Use Cases from a Large, Diverse Lay Group.18. Use Case Briefs and Extreme Programming.
No Primary Actor.
Too Many User Interface Details.
Very Low Goal Levels.
Purpose and Content Not Aligned.
Advanced Example of Too Much UI.
USE CASE 36 Research a Solution—Before.
USE CASE 37 Research Possible Solutions—After.
PART III. REMINDERS FOR THE BUSY.Chatper 21. Reminders for Each Use Case.
Reminder 1: A Use Case Is a Prose Essay.
Reminder 2: Make the Use Case Easy to Read.
Reminder 3: Just One Sentence Form.
Reminder 4: “Include” Sub Use Cases.
Reminder 5: Who Has the Ball.
Reminder 6: Get the Goal Level Right.
Figure 23: Ask “Why” to Shift Levels.
Reminder 7: Keep the GUI Out.
Reminder 8: Two Endings.
Reminder 9: Stakeholders Need Guarantees.
Reminder 10: Preconditions.
Reminder 11: Pass/Fail Tests for One Use Case.
Table 2 Pass/Fail Tests for One Use Case.22. Reminders for the Use Case Set.
Reminder 12: An Ever-Unfolding Story.
Reminder 13: Both Corporate Scope and System Scope.
Reminder 14: Core Values and Variations.
Reminder 15: Quality Questions across the Use Case Set.23. Reminders for Working on the Use Cases.
Reminder 16: It's Just3 (Where's Chapter 4?).
Reminder 17: Work Breadth First.
Figure 24: Work Expands with Precision.
Reminder 18: The 12-Step Recipe.
Reminder 19: Know the Cost of Mistakes.
Reminder 20: Blue Jeans Preferred.
Reminder 21: Handle Failures.
Reminder 22: Job Titles Sooner and Later.
Reminder 23: Actors Play Roles.
Reminder 14: The Great Drawing Hoax.
Figure 25: “Mommy, I Want to Go Home.”.
Figure 26: Context Diagram in Ellipse Figure Form.
Table 2 Actor-Goal List for Context Diagram.
Reminder 25: The Great Tool Debate.
Reminder 26: Project Planning Using Titles and Briefs.Appendices.
A.1 Ellipses and Stick Figures.
A.2 UML's Includes Relation.
Figure A.1: Drawing Includes.
GUIDELINE 13: Draw Higher Goals Higher.
A.3 UML's Extends Relation.
Figure A.2: Drawing Extends.
GUIDELINE 14: Draw Extending Use Cases Lower.
GUIDELINE 15: Use Different Arrow Shapes.
Correct Use of Extends.
Figure A.3: Three Interrupting Use Cases Extending a Base Use Case.
A.4 UML's Generalizes Relations.
Correct Use of Generalizes.
Figure A.4: Drawing Generalizes.
Draw General Goals Higher.
Hazards of Generalizes.
Figure A.5: Hazardous Generalization — Closing a Big Deal.
Figure A.6: Correctly Closing a Big Deal.
A.5 Subordinate versus Sub Use Cases.
A.6 Drawing Use Case Diagrams.
GUIDELINE 16: User Goals in a Context Diagram.
GUIDELINE 17: Supporting Actors on the Right.
A.7 Write Text-based Use Cases Instead.Appendix B. Answers to (Some) Exercises.
Chapter 3 (page 51).
Figure B.1: Design Scopes for the ATM.
Chapter 4 (page 60).
Chapter 5 (page 79).
Chapter 6 (page 85).
Chapter 7 (page 98).
USE CASE 38 Use the Order Processing System.
Chapter 8 (page 110).
USE CASE 39 Buy Stocks Over the Web.
Chapter 11 (page 138).
USE CASE 40 Perform Clean Spark Plugs Service.Appendix C: Glossary.
More and more people are writing use cases, for behavioral requirements, for software systems or to describe business processes. It all seems easy enough--just write about using the system. But, faced with writing, one suddenly confronts the question, "Exactly what am I supposed to write--how much, how little, what details?" That turns out to be a difficult question to answer. The problem is that writing use cases is fundamentally an exercise in writing prose essays, with all the difficulties in articulating good that comes with prose writing in general. It is hard enough to say what a good use case looks like, but we really want to know something harder: how to write them so they will come out being good.
These pages contain the guidelines I use in my use case writing and in coaching: how a person might think, what he or she might observe, to end up with a better use case and use case set.
I include examples of good and bad use cases, plausible ways of writing differently, and, best of all, the good news that a use case need not be the best to be useful. Even mediocre use cases are useful, more so than are many of the competing requirements files being written. So relax, write something readable, and you will have done your organization a service.
This book is predominantly aimed at industry professionals who read and study alone, and is therefore organized as a self-study guide. It contains introductory through advanced material: concepts, examples, reminders, and exercises (some with answers, some without).
Writing coaches should find suitable explanations and samples to show their teams. Course designers should be able to build course material around the book, issuing reading assignments as needed. (However, as I include answers to many exercises, they will have to construct their own exam material. :-) )
The book is organized as a general introduction to use cases followed by a close description of the use case body parts, frequently asked questions, reminders for the busy, and end notes.
The Introduction contains an initial presentation of key notions, to get the discussion rolling: "What does a use case look like?," "When do I write one?," and "What variations are legal?" The brief answer is that they look different depending on when, where, with whom, and why you are writing them. That discussion begins in this early chapter, and continues throughout the book.
Part 1, The Use Case Body Parts, contains chapters for each of the major concepts that need to mastered, and parts of the template that should be written. These include "The Use Case as a Contract for Behavior," "Scope," "Stakeholders and Actors," "Three Named Goal Levels," "Preconditions, Triggers, and Guarantees," "Scenarios and Steps," "Extensions," "Technology and Data Variations," "Linking Use Cases," and "Use Case Formats."
Part 2, Frequently Discussed Topics, addresses particular topics that come up repeatedly: "When Are We Done?," "Scaling Up to Many Use Cases," "CRUD and Parameterized Use Cases," "Business Process Modeling," "The Missing Requirements," "Use Cases in the Overall Process," "Use Case Briefs and eXtreme Programming," and "Mistakes Fixed."
Part 3, Reminders for the Busy, contains a set of reminders for those who have finished reading the book, or already know this material and want to refer back to key ideas. The chapters are organized as "Reminders for Each Use Case," "Reminders for the Use Case Set," and "Reminders for Working on the Use Cases."
There are four appendices: Appendix A discusses "Use Cases in UML" and Appendix B contains "Answers to (Some) Exercises." The book concludes with Appendix C, Glossary; and a list of materials used while writing, Appendix D, Readings.
In the late 1960s, Ivar Jacobson invented what later became known as use cases while working on telephony systems at Ericsson. In the late 1980s, he introduced them to the object-oriented programming community, where they were recognized as filling a significant gap in the requirements process. I took Jacobson's course in the early 1990s. While neither he nor his team used my phrases goal and goal failure, it eventually became clear to me that they had been using these notions. In several comparisons, he and I have found no significant contradictions between his and my models. I have slowly extended his model to accommodate recent insights.
I constructed the Actors and Goals conceptual model in 1994 while writing use case guides for the IBM Consulting Group. It explained away much of the mystery of use cases and provided guidance as to how to structure and write them. The Actors and Goals model has circulated informally since 1995 at http://members.aol.com/acockburn and later at www.usecases.org, and finally appeared in the Journal of Object-Oriented Programming in 1997, in an article I authored entitled "Structuring Use Cases with Goals."
From 1994 to 1999, the ideas stayed stable, even though there were a few loose ends in the theory. Finally, while teaching and coaching, I saw why people were having such a hard time with such a simple idea (never mind that I made many of the same mistakes in my first tries!). These insights, plus a few objections to the Actors and Goals model, led to the explanations in this book and to the Stakeholders and Interests model, which is a new idea presented here.
The Unified Modeling Language (UML) has had little impact on these ideas--and vice versa. Gunnar Overgaard, a former colleague of Jacobson's, wrote most of the UML use case material and kept Jacobson's heritage. However, the UML standards group has a strong drawing-tools influence, with the effect that the textual nature of use cases has been lost in the standard. Gunnar Overgaard and Ivar Jacobson discussed my ideas and assured me that most of what I have to say about a use case fits within one of the UML ellipses, and hence neither affects nor is affected by what the UML standard has to say. That means that you can use the ideas in this book quite compatibly with the UML 1.3 use case standard. On the other hand, if you only read the UML standard, which does not discuss the content or writing of a use case, you will not understand what a use case is or how to use it, and you will be led in the dangerous direction of thinking that use cases are a graphical, as opposed to a textual, construction. Since the goal of this book is to show you how to write effective use cases and the standard has little to say in that regard, I have isolated my remarks about UML to Appendix A.
The writing samples in this book were taken from live projects as much as possible, and they may seem slightly imperfect in some instances. I intend to show that they were sufficient to the needs of the project teams that wrote them, and that those imperfections are within the variations and economics permissible in use case writing.
The Addison-Wesley editing crew convinced me to tidy them up more than I originally intended, to emphasize correct appearance over the actual and adequate appearance. I hope you will find it useful to see these examples and recognize the writing that happens on projects. You may apply some of my rules to these samples and find ways to improve them. That sort of thing happens all the time. Since improving one's writing is a never-ending task, I accept the challenge and any criticism.
This is just one in a collection of books, The Crystal Collection for Software Professionals, that highlights lightweight, human-powered software development techniques. Some books discuss a single technique, some discuss a single role on a project, and some discuss team collaboration issues.
Crystal works from two basic principles:
The foundation book for The Crystal Collection, Software Development as a Cooperative Game, elaborates the ideas of software development as a cooperative game, of methodology as a coordination of culture, and of methodology families. That book separates the different aspects of methodologies, techniques and activities, work products and standards. The essence of the discussion, as needed for use cases, appears in this book in Section 1.2, Your Use Case Is Not My Use Case on page 7.
Writing Effective Use Cases is a technique guide, describing the nuts-and-bolts of use case writing. Although you can use the techniques on almost any project, the templates and writing standards must be selected according to each project's needs.
ONE MONTH ACCESS!
Get unlimited 30-day access to thousands of Books & Training Videos about technology, professional development and digital media If you continue your subscription after your 30-day trial, you can receive 30% off a monthly subscription to the Safari Library for up to 12 months.