Writing Use Case Descriptions

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 aStory • A use case description is, in a sense, a story of how an actor uses the system to achieve some end result. • Actor mustSTART 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 unusualbehavior 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.

Writing Use Case Descriptions