Hi all

One of my colleagues, Greg Cathcart, reminded me some time ago that there are people out there who have to use use cases for some reason or another. Also there are many people out there getting into terrible messes when using use cases. So I feel the need for a CoadLetter on the subject. I have only had bad experiences with use cases so I wanted to take a step back on this one and:

1. let those friends and colleagues who like them or have used them successfully speak
2. maybe learn something myself in the process.

I hope you enjoy it, find it controversial enough to stir some discussions, and, hopefully, lead to some firm conclusions. Let me know what you think.

Have fun

Steve

Stephen R Palmer

ps STUTTGART 24th - 25th October: TogetherSoft International User Conference - "IMPROVE YOUR PERFORMANCE". Sponsored by HP and other TogetherSoft partners, with influential author and technology visionary, Peter Coad, President, CEO and Co-Founder of TogetherSoft, speaking alongside other TogetherSoft consultants, designers, developers and various leading speakers from the industry. See www.togethersoft.co.uk for details.

Use Case Do's and Don'ts: An Informal Survey

There is probably enough content for a couple of magazine articles in the lists below. Rather than comment myself. I'll let you, the reader be judge and jury, and draw your own conclusions.

Use Case Do's:

Granularity and completeness

• Do have a clear idea of the system you intend to build/describe using use cases
• Do build a context diagram that identifies the use cases and the transactions that trigger them
• Do the 50,000 foot view use case model first
• Do nest use cases.. have a high level system diagram with use cases of coarse granularity, and a more detailed diagram for each.
• Do iterative and incremental use case elaboration.  Only elaborate those that look scary, or that customers prioritize. Elaborate main success scenarios first.
• Do ensure all use cases are described at the same "level", that is, one use case is not seventy pages, while every other use case is 2-3 pages
• Do limit the number of Use Cases of a given application (or it won't be manageable)
• Do ensure there are no gaps in system functionality between use cases
• Do switch perspectives when appropriate, i.e. stuck on a set of use cases, flip to features, get somewhere, flip back.  They are not mutually exclusive.
• Do iterate use case development alternating with problem domain modeling. The two processes feed each other.
• Do focus on the highest risk uses first.

Naming and Format

• Do make actors names as specific as possible (no "person" or "mainframe")
• Do distinguish between primary and secondary actors (a primary actor is the initiator of the use case, a secondary actor is a participant)
• Do ensure the name of each use case reflects the actor's goal in interacting with the system
• Do use specific verb phrases as use case titles.
• Do keep the use case titles to five words.  Should be simple, descriptive, and high-level.
• Do create a standard use case template agreed upon by all of the use case writers
• Do, if you want/need a textual use case, use a standard template.  I suggest Alistair Cockburn's.
• Do the following use case structure:  name, actors, post-condition, pre-condition, business rules
• Do clearly identify external events and system answers (for instance by using 2 columns)
• Do have a project standard for style and detail, for naming use cases, and documenting the business requirements text for the use case -- this ensures that the analysts stick to the true business requirements and not engage in amateur system design.  The name should be a verb phrase to express the behavioral essence of use cases, and should be expressed from the system's point of view -- what the system does, not what the actor is doing.  The actor's goals are part of the documentation of the actor, not part of what the system does.
• Do always write your use case post-condition first:  it is the business goal for the use case.
• Do ensure the diagrams use proper UML notation
• Do keep general description to several paragraphs.

Content

• Do ensure all use cases provide value to at least one actor (exception: use cases that are associated with another use case via the include relationship)
• Do create use cases that produce an observable result to at least one actor.
• Do ensure each high-level use case achieves some business goal for an actor
• Do ensure the description of the use case captures all observable value required by the actor in achieving the goal given by use case's name
• Do limit the use case to the presentation of users requirements
• Do ensure the use case contains the flow of events to reach the goal successfully and unsuccessfully.
• Do make use case alternate courses what you do on violation of conditions:  pre-, post-, business rules.
• Do describe the required action for each exception and for each option (i.e. if you have Verify item, describe what action has to be taken if the verification is false)
• Do describe multiple scenarios for each use case; successful completion and any unsuccessuful completions.
• Do choose a template that explicitly shows the scenarios within each use case (main success scenario, plus others).

Additional Documentation

• Do have a separate document for the details of business rules that, if included in the documentation of a use case, would lead to bloated use case narratives.  The same business rule is often invoked in many use cases -- that is one reason this is a good practice. Another is that the use case description is thereby kept short and sweet -- imagine if one had to insert a description of how to compute yield to maturity as part of the statement that the system is to provide this figure when the user selects a bond and inputs a price and settlement date.
• Do express more complex requirements on linked text documents or on state chart or activity diagrams
• Do use activity diagrams to define individual use cases (normal flow & alternatives)
• Do use a simple table format instead of a use case narrative text as the way of conveying requirements for data input and display.  Tables are a better format for this purpose than a narrative text.
• Do keep the detail out of the weeds.  Code-level detail belongs in code.  Detailed sequences and activities belong in Sequence diagrams and Activity diagrams.
• Do consider your uses cases as the starting point for System Test Cases.
• Do consider use cases (or individual scenarios) when defining programming cycles.

Language

• Do test your use cases against their intended audiences early on i.e. can your customer understand them or can they even write some of them?
• Do express use case activities in domain language of the user.  Only use technical terms in a 'technical' domain.
• Do involve a "user" in the writing process - these are the user's requirements, not the IT teams.

Getting Help

• Do use somebody with experience of writing use cases (if the team doesn't include someone like this, hire a mentor).
• Do take some training or practice in writing use cases.
• Do read Martin Fowler's writings on the subject
• Do get a good book on Use Cases, like from Cockburn
• Do get a good book, such as Writing Effective Use Cases, Alistair Cockburn, ISBN 0201702258.

Use Case Don'ts

Granularity and completeness

• Don't nest too deep... 2 levels is generally adequate
• Don't get bogged down in use cases (analysis paralysis)
• Don't spend months writing a use case
• Don't write a use case about a part of the system for which you have no domain expertise
• Don't write more use cases than anyone will ever read
• Don't have holy wars over use case modeling. What is important in the long run is the finished system not the use case model.
• Don't proceed as if a use case model begins with and is based on identifying use cases.  It isn't.  It is based on identifying first the goals of the sponsor and the actors, that is the roles in which external parties and systems will interact with the new system.  The actor model must precede the use case model, just as in the days of structured analysis and design, a context model was the proper first diagram. The use cases are derived from an analysis of the goals of the sponsor and actors.
• Don't try to fill in a complete template all at once.  Not all the fields will apply, and some audiences don't need to see what's blank.
• Don't create separate use cases for creating, retrieving, updating or deleting objects unless absolutely necessary.
• Don't create use cases to describe system interactions such as app server to web server. It sounds ludicrous but I've seen it done many times!

Don't describe how the system works internally - describe interactions between the actors and the system. If you find yourself writing steps the system takes without interaction with an actor, consider whether it really is a requirement (or are you doing design), or if it is a business rule/process (in which case, document it with a technique that is more appropriate, such as an activity diagram).
• Don't elaborate all the use cases (or all the scenarios) in one go - iterate.
• Don't elaborate a use case that is "obvious" - if you are writing a use case, but learning nothing new about the system/domain, then you could be doing something more useful.

Content

• Don't include user interface or system design elements in the use case
• Don't draw a use case diagram and say Im done.
• Don't believe anyone who tells you that use case modeling is simply about creating ovals and stick figures in a case tool. Use case modeling is tough.
• Don't get dis-heartened if you find use case modeling difficult - it probably indicates you  are doing it properly.
• Don't suppose the use case is, in the sense of identity, a text narrative.  It is not.  A use case is something the system does that is of value to a sponsor and serves the interests of an actor.  This service is identified not by a text narrative, but by a verb phrase briefly identifying what the system does.
• Don't get worked up about extends/includes/generalization among use cases. Use plain English and refactor.
• Don't limit the actors to human actors (i.e. forget the actors representing other systems or time events triggered by a date and/or a time)
• Don't try to design the technical solution

Additional Documentation

• Don't do use case modeling in isolation. Use case modeling should be balanced by domain analysis (class identification and possibly diagramming), interface specification (of interacting systems), and architectural development and prototyping.
• Don't throw away existing requirements specifications (such as an SRS). These can be used to feed the use case modeling process

Language

• Don't use software words, such as database

Getting Help

• Don't undertake a large-scale use case modeling effort without veteran use case leadership or mentoring
• Don't give up on use cases!
• Don't take it too seriously.
• Don't let Steve Palmer's attitude towards use cases put you off :-)

Contributors in no specific order:

©2001 Giraffe Productions