i
W
RITING
E
FFECTIVE
U
SE
C
ASES
( * * P
RE
-
PUB
. D
RAFT
#3 * * )
Alistair Cockburn
Humans and Technology
copyright A.Cockburn, 1999-2000
Addison-Wesley
date: 2000.02.21
ii
1
1
P
REFACE
More and more people are writing use cases to describe business processes and the behavioral
requirements for software systems. It all seems easy enough - just write about using the system.
Faced with writing, however, one suddenly asks, "Exactly what am I supposed to write - how
much, how little, what details?" That is 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 articu-
lating 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 writing and in coaching: how a person might think,
what they 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 best to be useful. Even mediocre use cases are useful,
more useful than many of the competing requirements files being written. So relax, write
something readable, and you will have done your organization a service already.
Audience
The book is aimed at professionals who read and study alone. It is organized as a self-study
guide. It contains introductory, intermediate and advanced concepts, examples, reminders, and
exercises with answers.
Project and use case coaches should find suitable explanations and samples to show their teams.
Course designers and instructors 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 :-).
Organization
The book is organized into four main parts: introduction to use cases, the use case body parts,
frequently asked questions, reminders for the busy, and end notes.
2
Chapter .
- Page 2
The Introduction to Use Cases 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 varia-
tions 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
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 & Actors” , “Three Named Goal Levels” ,
“Preconditions, Triggers, Guarantees” , “Scenarios and Steps” , “Extensions” , “Technology &
Data Variations” , “Linking Use Cases” , and “Use Case Formats” .
Frequently Asked Questions addresses particular topics that come up repeatedly: “When are
we done?” , “Scaling up to Many Use Cases” , “Two Special Use Cases” ("CRUD use cases" and
"Parameterized use cases"), “Business Process Modeling” , “The Missing Requirements” , “Use
Cases in the Overall Process” , “Use Cases Briefs and eXtremeProgramming” , and “Mistakes
Fixed” .
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 reminders are
organized as “Each Use Case” , “The Use Case Set” , and “Working on the Use Cases” .
The End Notes contains four topics: “Appendix A: Use Cases in UML” , “Appendix B:
Answers to (some) Exercises” , “Appendix C: Glossary” , and “Appendix D: Reading” .
Heritage of the ideas in this book
Ivar Jacobson invented use cases in the late 1960s while working on telephony systems at
Ericsson. Two decades later, he introduced them to the object-oriented programming community,
where they were recognized as filling a significant gap in the development process. I took
Jacobson’s course in the early 1990's. The ideas here are generally compatible with Jacobson’s
descriptions, but I have slowly extended his model to accommodate recent insights regarding the
writing. While neither he nor his team used the words goal and goal failure, it became clear to me
over time that they had been using these notions in their teaching. In several comparisons, he and I
have found there are no significant contradictions between his and my models.
I constructed the Actors & Goals conceptual model in 1994 while writing use case guides for the
IBM Consulting Group. The Actors & Goals model explained a lot of the mystery of use cases, and
gave guidance as to how to structure and write use cases. It circulated informally since 1995 from
http://members.aol.com/acockburn, later at www.usecases.org, and it finally appeared in the
Journal of Object-Oriented Programming in 1997, entitled "Structuring use cases with goals".
Chapter .
Page 3 -
3
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 & Goals model, led to the explanations in this book
and the Stakeholders & Interests model, which is new in this book.
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 retained Jacobson’s
heritage of use cases. However, the UML standards group has a strong drawing-tools influence,
with the effect that the textual nature of use cases was 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 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 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 place of use cases in the
Crystal
book collection
This is one in a collection of books, the Crystal collection, that highlights lightweight, human-
powered software development techniques. Some books discuss a single technique, some a single
role on the project, and some discuss team collaboration issues.
Crystal works from two basic principles:
• Software development is a cooperative game of group invention and communication. Software
development improves as we improve people's personal skills and improve the team's collabo-
ration effectiveness.
• Different projects have different needs. Systems have different characteristics, and are built by
teams of differing sizes, containing people having differing values and priorities. It cannot be
possible to describe the one, best way of producing software.
The foundation book for the Crystal collection is Software Development as a Cooperative
Game. It works out the ideas of software development as a cooperative game, of methodology as a
coordination culture, and of methodology families. It separates the different aspects of methodol-
ogies, techniques from activities, work products and standards. The essence of the discussion, as
needed for use cases, is contained in “Your use case is not my use case” on page 20.
