Writing Use Case Descriptions

Materials taken directly from

Use Case Modeling by

Kurt Bittner and Ian Spence

Details

At some point, one has to sit down and describe the details of what happen.

So: Who writes Use Case Descriptions Getting Started Managing Detail Summary

1. Who Writes Use Case Descriptions? Primarily an individual activity.

Sometimes a pair – each reviewing other’s work Sometimes a small team work on related sets of

use cases Mentoring Approach needed – regardless

From more experienced team members. Maybe a consultant providing expertise Organization needs to develop its own experts. An internal ‘writers group’ to share experiences

Reviewing Use Cases – a group activity!

Programmers Write Poor Descriptions Use Cases focus on ‘what’; code is an expression of ‘how’ the system will do things.

Approach may be quite different. Approach as if solving a mystery – the mystery of

what the system needs to do in order to be useful to the people who will use it.

If programmer is unable to detach from coding role and take the holistic view (want: crank code) forcing them to write use cases is a bad idea. Many programmer don’t like it; aren’t very good at it.

Programmer’s often aren’t very good at writing Use Cases…

Story analogy: Deciding what the system does requires vision, creativity, and ability to describe what does not yet exist – not unlike the process of writing a story. Programmers tend to think too literally & analytically;

immediately start thinking about how the system will work; how components will be structured.

May produce systems that are ‘technically elegant’ but unusable because they do not solve a real business problem.

Before you can write code - need to know what the system has to do. It’s hard for a programmer to wait.

Characteristics of a Good Use Case Author Ability to synthesize

Wish lists – only tell us the system must satisfy ‘some condition’

How it gets to this condition and the intermediate steps the system must go through to get there are not explicitly stated.

Use Case writer must comb through the requirements adding information gleaned from other sources to create a coherent story.

Ability to approach a problem systematically Team members responsible for domain entities,

business rules, and glossary terms requires a systematic approach.

Some domain knowledge or understanding of the users of the system

Characteristics of a good Use Case Author At least some understanding of software development

Use Cases are about the ‘what.’ Software development is about the ‘how.’ If a system MUST behave a certain way, the

use case should describe it. If the designer has complete freedom to

exercise ‘creativity’, the use case should remain silent about exact details of how the system carries out the use case.

An ability to write well. Assign the right people to this task…

2. Getting Started Actually writing of the use case description is a

solitary rather than a group activity. Use a template (style guide)

Need not be terribly formal Decide on what will be in the use case…

Write simply, directly, and deliberately. Write in active voice (The system validates….) Write in present tense (The system validates…

Not what the system ‘will’ do… Use Newspaper style

Use major headings – then fill in details if needed. Remember: the reader of the use case will rely on

the use case to design and build the right system! Every word, sentence must be carefully chosen to

convey meaning very precisely.

2. Getting Started – Treat Use Case like a Story A use case description is, in a sense, a story of how an actor

uses the system to achieve some end result. Actor must START the sequence of events

System can act with other actors until final result. Good beginning makes the difference.

Use cases don’t start spontaneously Some event is initiated by the actor “The use case begins when the actor does something”

Story has a plot: it indicates who says/does what and when they do it. Typical pattern: “The actor does xxxx; then the system does yyyy

in response. Use Cases have a clear ending; A good use case has a

purpose; it delivers some result to one or more of its actors and then it terminates. To make sure that everyone understands when and how the use

case ends, make the ending: “The use case xxx ends when yyy…”

2. Getting Started – Make Decision about the Depth of Detail Required No standard answer Testers & maintainers need to know what the system

is supposed to do so that they can determine if the system is working as intended.

Team has domain expertise? May consist of outlined flows supplemented with

storyboarding and/or prototypes Systems with strict regulatory / safety-critical systems

require more formality in the specs. Expand until ALL STAKEHOLDERS are satisfied that

they understand and approve the description of behavior expressed in the use case.

2. Getting Started – Make Decision about the Depth of Detail Required = more All use cases are not equally important.

Some require much detail; others leave as outlines Remember, purpose of use case is to capture the

interactions of the actors and the system. Focus on what actor does and what system does in

response. Use Case describes what system does but not how

user interface or internal components collaborate to do what it does. – No implementation.

Capture what system does, but be indifferent to how the behavior is implemented…

2. Getting Started – Make Decision about the Depth of Detail Required – not just text

Text: Don’t rely on Just Text – not always the ideal medium for describing behavior.

Class Diagrams: sometimes class diagrams in the domain model used by the use case can aid an explanation.

Storyboarding: Another way: – a sequence of screen shots from a user interface prototype that depicts flow of events. Can be very valuable.

Again, storyboards represent what the system COULD look like and not intended to exact depictions of what the system WILL look like

Activity Diagram - another way: Must be such that all stakeholders can understand the

descriptions of the system being proposed…

2. Getting Started – Make Decision about the Depth of Detail Required – Prototype User Interface Use prototypes to describe the User Interface (UI)

leaving use cases to describe what happens behind the screens. Use Cases – tedious to write; don’t generate much good

feedback on whether UI is good or not. People want to SEE the interface; FEEL the interface

before they are comfortable. So, use a prototype in conjunction with a use case

Prototype – presents the look and feel of the UI Use Case describes the behavior of the system behind the

screens.

3. Managing Detail Fear of too much detail.

Can be problem if this obscures real flow Need detail to avoid ‘useless case.’ Challenge: control the detail.

No ‘levels’ or decomposition of use cases. Are not used to divine the architecture Remember: goal to describe behavior no

matter how it is design and implemented. Add more structure? No longer see what is

done, but do know how it does it!!! So, we are lost.

Managing Detail: Detail level in Use Cases Remember: Use cases must present the actor

with independent value. Example: Logging in? Good use case? Actor satisfied with logging in? No. ATM: dispensing cash! Deposit cash! Good Logging in; printing receipt? No. These are only

means to accomplish the goals… Only systems of systems warrant ‘levels’ of use

cases – far beyond our concerns here…(for VERY large independent yet collaborating systems.)

Managing Detail: Use Glossary and Domain Model to Capture Definitions Glossary: Used to describe simple definitions and more complex terms

in a use case that often require detailed explanations but do not materially add to the flow of events.

Rather than put all these attributes (like ‘memorabilia data’) into the Use Cases and clutter them (and miss the flow for the detail), use Glossary: Example: ‘member data’ from a use case might be defined in

the Glossary where all the attributes are named… Example: ‘memorabilia order’ might be defined in the Glossary

to contain the attributes the Chapter Advisor sees. Example: ‘memorabilia inventory’ might be defined in the

Glossary and contain all the attributes the International Secretary sees

Glossary – continued…

Of course, Glossary is used for many other terms/definitions too.

This is a way to add detail to your use cases (e.g. attributes here)

Rather than say ‘customer information’ and assume someone will later work out the details, define it and put the details in the Glossary!

Effective use of Glossary will simplify the use case descriptions by allowing the use case to focus on describing behavior not terminology!

Managing Detail: Use Glossary and Domain Model to Capture Definitions Sometimes glossary terms are related to

each other is well-defined ways (define one in terms of the other….; cross-references…) Implies there is some structure / relationships in

our concepts / terminology When true, consider using a Domain Model

Will help simplify the Glossary in the same way as the Glossary helped to simplify the use case details.

Domain Model – also called the Business Object Model – captures relationships among concepts as well as the structure of information within the concepts.

Domain Model DM does not represent the design of system;

rather, defines in precise terms a set of concepts used in the problem domain. The fact that the domain model will eventually give rise to

design elements is NOT license to start capturing design info while working on the use cases. Focus on one thing…

Domain Model appears like fully-attributed list (plus perhaps some nouns, and other objects that may not be part of your model.) But the format is similar; structure and multiplicity … are included…

Domain Model should not include any ‘bridge’ entities or other helping structures that may have developed in creating a fully-attributed list – only concepts from the problem domain (no implementation considerations).

Domain Model – continued…

By capturing information in the domain model, it is possible to remove some details from the use cases.

Glossary and Domain Model are complementary and sometimes interchangeable.

If you define a concept in the domain model, you would not need to define it in the glossary..

Use both Glossary and Domain Model Summarize: Put term in only one place. If concept is related to other concepts in well-defined ways

(orders have items…) use the domain model. If concept is just a defined term, use the glossary. Recommend: leave a placeholder in the glossary that points

to the domain model for all terms defined in the domain model. Allows glossary to be a complete index to all definitions. Can use hyperlinks. If not, bold glossary or domain model

elements in your use cases. Remember: Glossary and Domain Model are not ‘ends’ unto

themselves – only exist to clarify requirements and use cases.

Capture Business Rules in a Domain Model Business Rules: sets of requirements that

pose special problems. Absolutely ‘requirements’ that normally constrain

how the business itself works independent of how any solution supports the business.

Examples: A person must be a member of the cooperative before

thy can make a purchase A customer may have no more than one outstanding

order. Customers whose bills go unpaid for more than 60 days

will be referred to a collection agency…

More on Business Rules

Some business rules relate to how information is validated…

Other business rules may related to how work is performed….

Again, these can simplify use cases Would be distracting to stop after every step to describe

how data is validated….

Be sure to include your business rules in the supplementary specs along with your Glossary and Domain Models…

Sub-flows can Simplify Complex Descriptions

Use Case descriptions will contain sequences of one or more steps that can be given a name… a sub-flow name.

Sub-flows are labels that refer to certain sequences in a flow.

Can refer to a sub-flow by name in other parts of use case description…as we have stated, such as Perform subflow whocares…

Also, as mentioned, these subflows are normally separately documented.

Consider the following sub-flow example:

Sub-flow example: S1 Login 1. When the user enters the system for the first time, the system

prompts them for the password. 2. The user enters this password (the system echoes only ‘*’ characters

to the screen as they do so. When the user indicates completion of entering the password, the system compares the password to the one associated with the user’s profile.

3. If the password matches, the user is granted access to the system and the use case continues. A. If the user does not enter the correct password, the system reports that

the password is incorrect. 1. The user is given two additional opportunities to enter the correct password. 2. If the user fails to enter a correct password in three attempts, the system logs

the failure attempt date and time along with the user profile information and the user is logged off the system.

B. If the password matches, the user is granted access to the system and the use case continues; otherwise, the system reports that the password is incorrect.

By moving this text to a sub-flow, we simplify the use-case description by allowing this behavior to be referred to by simply saying: ….Perform sub-flow Login…

within the use case description where we need to reference the behavior..

Use Alternative Flows to Capture Unusual or Complex Behavior Recall, an alternative flow is a separate

section of the use case description that typically presents optional or unusual behavior that is not part of the normal behavior of the use case.

Alternatives are used to present the details of alternative behavior and exception handling.

Can also describe complex behavior that is important, but if presented in the main flow might obscure the overall flow of events.

Don’t Fill Your Use Cases with CRUD Use Cases filled with CRUD (Create, Read, Update, and Delete) often

don’t add much to a specification document. May be better to write a simple use case description (typically an outline is

sufficient) them move quickly to developing a prototype to validate the requirements and make sure you’ve got the right user interface, and then move on to design. Faster than creating the use cases!

Use Cases for simple CRUD behavior don’t add much value to ensuring that the system is doing the right thing. Don’t help much here….

To say, here’s something important, and here’s how to validate it - is not too exciting and is clear. No real flow of events: Enter data; validate data, etc…. Not much to typical CRUD behavior in a flow of events.

Historically, teams waste a lot of time developing use cases for CRUD behavior and not have enough time to dig into the ‘real’ behavior of the system. Missing the hard stuff… Employing use cases for CRUD increases risk that we have time to

properly address the complex use cases.

More on CRUD Although technically appropriate to employ use cases to

describe this kind of behavior, it is probably not a great use of time to describe this behavior in terms of use cases.

Use Cases should contain more than CRUD.

The important parts of the CRUD behavior – the data validation – can be captured in the domain model along with the definition of the data itself by specifying the cardinalities on relationships, constraints on the values of attributes and other information that can be used to validate behavior. Often prototypes produce by these tools are more than adequate for production-quality work and can be easily evolved.