Author Topic: Use Case Descriptions  (Read 3981 times)

fluxtah

  • EA User
  • **
  • Posts: 144
  • Karma: +0/-0
    • View Profile
Use Case Descriptions
« on: March 08, 2004, 12:58:13 am »
Hiya,

I am reading this Use Case Modelling book by Kurt Bittner and Ian Spence.

There use case style requires some text formatting, ie glossary words are bolded within the Use Case descriptions.

Also they use private extension points within the description to label certain areas of the flow or label an Alternate flow point.

I was wondering if anyone uses this (IMO difinitive) style of Use Case Descriptions? And do you use EA to do this or something like MS Word?

best regards

Ian

sargasso

  • EA Practitioner
  • ***
  • Posts: 1406
  • Karma: +1/-2
  • 10 COMFROM 30; 20 HALT; 30 ONSUB(50,90,10)
    • View Profile
Re: Use Case Descriptions
« Reply #1 on: March 08, 2004, 03:45:10 pm »
Ian,

We have tried "all sorts" of UC templating.  The conclusion I have come to is that flexibility is the best option.

Consider your goals in writing use cases.  Our "current" goals here are to provide an interface between the user and the development team, agreed to by both, as defining the framework around which the business requirements can be translated into system level requirements.
Within those goals I have found generally that on a given business system some use cases are extremely trivial and others extremely copmplex.

I try and get the analysts here to document use cases at the minimum possible level needed to obtain a common understanding on each individual use case.  That is, I dont want someone spending 2 days writing up the "Login" use case if it can be adequately explained using a quick EA Note "use the corporate standard login for secure client apps to allow access".

On the other hand, the UC "Construct and report estate financial management plan" probably requires considerable formalisation to come to the agreed level of understanding.

I have a set of what I call "starter templates" for the anaysts to use in the latter cases.  These are word docs, with filled in examples for each section.  I provide three levels of these and the analysts concerned are free to choose:
a) to use them or not, and
b) to change them to suit themselves.

These documents are NOT used as a formal part of the system requiremtns and design specs, they are used as working papers by the analysts in arriving at the needed level of understanding of an indivual use case.  We get them to record the salient information into the formal requirments repository (EA!).

hth
Bruce
"It is not so expressed, but what of that?
'Twere good you do so much for charity."

Oh I forgot, we aren't doing him are we.

sargasso

  • EA Practitioner
  • ***
  • Posts: 1406
  • Karma: +1/-2
  • 10 COMFROM 30; 20 HALT; 30 ONSUB(50,90,10)
    • View Profile
Re: Use Case Descriptions
« Reply #2 on: March 08, 2004, 03:49:19 pm »
Oops, I forgot to reply to the direct part of you question again.

I would be [glb]extremely[/glb] suspect of any technique that relied on technical mechanisms such as bolding or internal hyperlinks to achieve some sort of information delineation.

KISS!
"It is not so expressed, but what of that?
'Twere good you do so much for charity."

Oh I forgot, we aren't doing him are we.

fluxtah

  • EA User
  • **
  • Posts: 144
  • Karma: +0/-0
    • View Profile
Re: Use Case Descriptions
« Reply #3 on: March 09, 2004, 04:12:52 am »
Hi Sargasso,

I agree with not overdoing it, ie taking 2 days to write a login use case, if the behaviour of a use case is so obvious.

I don't think I explained myself very well before posting! It was the HTML documentation I wanted to show glossary terms used in the use case descriptions in bold.

In the book they bold their glossary terms as well as use private extension points, which are basically headers such as the following snippet use case description taken from the book:

{Insert Card}

1. The use case begins when the actor Customer insterts a bank card into the card reader on the ATM.

2. The system allocates an ATM session identifier to enable errors

{Read Card}

3. The system reads the bank card information from the card.

.............................
snipped*


each bolded piece of text within the use case description denotes a glossary term which explains the terms used in detail.

I have found a way to bold by using html tags such as <b> for bold and <i> for italic but not sure if it is ideal.

Ian




angel-o-sphere

  • EA User
  • **
  • Posts: 112
  • Karma: +0/-0
    • View Profile
Re: Use Case Descriptions
« Reply #4 on: March 09, 2004, 09:04:14 am »
I use similar formats, and if the tool would allow it I would also bold for glossary terms etc.

In the current project most analysts have no experiance with Use Cases, so I gave a very simple document format for writing them down. Also we make very simple use cases as well. Every standard use case is broken into mini use cases, partly only describing one edit action on one single field.

The reasons where: easyer writing for unexperianced analysts and the very complex pre and post conditions and default values needed for data fields.

We did everything with Word .... and now we want to try a new tool from steeltrace.com, Catalyst.

Catalyst has an EA integration feature (not published on their web site) and makes working with hughe sets of use cases easyer (hopefully).

The only thing I am meanwhile convinced off: standard word processing tools, regardless if they produce interlinked HTML or doc format or what ever, are a real pain to use for documenting use cases.

Thats likely the reason why people propose to use the simplest format possible ...

To bad that EA offers no assistance regarding that, using the note field or the requirements tab seems inapprobriated.

Regards,
  angel'o'sphere

fluxtah

  • EA User
  • **
  • Posts: 144
  • Karma: +0/-0
    • View Profile
Re: Use Case Descriptions
« Reply #5 on: March 09, 2004, 10:37:21 am »
EA does have a scenario tab to describe flows but... I am now confused as I thought that a Use Case Description differs from a scenario, from what I am reading a Use Case Description describes the flow of events either briefly or in great detail as the example snippet above in my last post.

A Use Case scenario is an instance of a Use Case, or so my book puts it.

*confused*

For now I am assuming that the scenario tab is for use case descriptions...

Ian

mchiuminatto

  • EA User
  • **
  • Posts: 113
  • Karma: +0/-0
    • View Profile
Re: Use Case Descriptions
« Reply #6 on: March 09, 2004, 11:02:18 am »
As I understand Use Cases, they return a meaningful and concrete value to the actors. I put a description of that value in the note field in EA (with the title GOAL). I add a little bit of context description in this field, anything that helps to understand the use case goals. (I try to keep it as brief as possible)  

But  there is a dialog between the Actor and The System before the actor obtains the value from the system.  I document these dialogs as  scenarios: basic path, alternate path or exception path.

I see the goal, the scenarios, the pre and post conditions as the use case description set.

Correct me if I'm wrong please.





Regards.

Marcello

Bruno.Cossi

  • EA User
  • **
  • Posts: 803
  • Karma: +0/-0
    • View Profile
Re: Use Case Descriptions
« Reply #7 on: March 09, 2004, 11:13:34 am »
Marcello,

this is pretty much what I do, too. I use the "Note" field to describe what is it that the Use Case does (e.g. Use Case "Open Customer Account" would in a sentence or two describe what the account is, what does opening it mean.)
Scenario describes the flow of events, the process itself. Scenario in my mind describes in high level what will later on be described in detail in sequence an activity diagrams.

Bruno
http://wiki.eausergroup.org - WIKI for all things EA

fluxtah

  • EA User
  • **
  • Posts: 144
  • Karma: +0/-0
    • View Profile
Re: Use Case Descriptions
« Reply #8 on: March 09, 2004, 11:21:38 am »
To my understanding that is entirely correct.

The way I am learning to do it has great benefits, by bolding glossary terms you can take a bulk of the use case out of the description, and also by using private extension points able to have points where alt flows could occur.

Also how to handle subflows using EA? sorry about constantly inserting 'my book' but after reading it highlights some interesting features that could be further automated, so far I have found a work around by embedding html tags in the scenarios so when i export html documentation it shows as in snippet i posted above.

It would be nice to be able to reference glossary terms in use case descriptions in some unobtrusive manner, bolding seems to do this though it would be good to click on them.. possibly have the term appear in a popup window if the reader of the use case needs more information on the term to understand the use case description but this is functionality of the html documenation output, I should really look into EA's automation  :o

btw the book is at http://www.usecasemodeling.com

regards

Ian
« Last Edit: March 09, 2004, 01:59:13 pm by fluxtah »

sargasso

  • EA Practitioner
  • ***
  • Posts: 1406
  • Karma: +1/-2
  • 10 COMFROM 30; 20 HALT; 30 ONSUB(50,90,10)
    • View Profile
Re: Use Case Descriptions
« Reply #9 on: March 09, 2004, 04:59:04 pm »
I certainly agree that having automatic links to glossary items would be a good idea - probably even worth dumping in the suggestions list.

In terms of using Note and Scenario tabpages, we follow the same general ideas as expressed above.  However, I will add the following to explain how we suggest they do it.

When the use case is initially "agreed" in our requirements review sessions, we tend only to give it a name and the first guess at complexity (under the theory that initial impressions are usually the best and if we dont do it initially it gets forgotten.) In addition, if there is strong evidence that different users have different names for the same thing we will create a list of Aliases.

If the team has been diligent in creating the external requirements we create a working diagram for the use case and link the associated requirements.  This diagram is distributed for review at the next session (or if we are good little workers, after any breakouts in the current session).

The use case is then assigned to a particular analyst as the "owner" of the use case (using the Author field). That analyst writes the use case description (Note) along the following lines:
- what invokes the UC (or alternatively how does it start)
Quote
"The process customer payment use case is invoked whenever a new payment is received from a customer, either as a personal payment, a cheque through the mail, an electronic payment or when we are notified of a direct credit receipt in the daily bank statement."

- what is the outcome(s) of the use case with respect to the real world and the system persistence model.
Quote
"The use case raises a GL posting against the customer accountand either produces a letter of payment to the customer or, in the case of personal payments, a receipt.

- (if not implied by the outcomes) what indicates that the use case is ended
Quote
"The use case ends after the GL interface returns a validation of the posting"

- what other general information may be salient
Quote
Sometimes payments for multiple trades are received in the one payment - this means that the "Allocate Payment" use case may be invoked.
Sometimes only partial payment is received - this should not present a problem to processing the payment


You can see we get quite a lot of information summarised very quickly in this way.  We also use the Maintenance items fairly repeatedly at this stage to note issues, ideas and proposed changes.

From the above example, you can see that the UC has some pretty apparent candidate scenarios based on the payment types to be handled.  Further, there is an indication that an <<extends>> relationship might exist to the "allocate payments" use case.

The analyst will then draft up their ideas on the scenarios.  These are discussed at the next review.

In the main, I have found that about 85% or so of the draft scenarios are real, the remainder are duplicates and can be merged with others or are actually candidates for separate use cases.  We try to keep the number of use cases as small as possible - keeping in mind my idea that they are a framework rather than a 3 volume requirement spec (or even worse a system design done by the requirements analysts).  Further, the business users tend to focus on the detailed requirements rather than detailed use case annotations as it is, of course, blinding obvious to them how they do their job.  They will spend some time reading the requirements to ensure that we haven't left something out that they "cant possibly live without", whereas they tend to pay less attention to the same details if they are hidden in the use case annotations.

We finish up the UC doc cycle by agreeing on the true set of scenarios - based on the idea that each scenario represents a unique usage of the system with diffferent aspects represented that must be satisified if the requirements are fully met.
"It is not so expressed, but what of that?
'Twere good you do so much for charity."

Oh I forgot, we aren't doing him are we.

Captain_Ding_Dong

  • EA Novice
  • *
  • Posts: 5
  • Karma: +0/-0
    • View Profile
Re: Use Case Descriptions
« Reply #10 on: April 22, 2004, 04:25:00 am »
A use case consists of a set whose elements are  the possible steps through the use case - producing a result for an actor.  The steps are written as a list of statements. If there is only one possible path through the use case the senario and the required steps are the same thing.  Should there be a number of different paths (branching, conditionals etc) possible through the use case, these are represented by a different senario.  You may have many possible senarios to one use case.  



   

pchang

  • EA Novice
  • *
  • Posts: 4
  • Karma: +0/-0
    • View Profile
Re: Use Case Descriptions
« Reply #11 on: July 09, 2004, 12:23:05 pm »
Okay...If each scenario represents one path through the use case, what is the fewest number of different scenarios I need to document for the following use case?

Use Case: One person taking Delta Airlines from San Diego to New York City.

Suppose Delta has 2 different fares ($300, $600). Each fare has 3 different take off times from San Diego.  Each take off time has 4 different connecting flights before reaching New York city.

Do I need to document all 24 scenarios in the "UseCase element"?  Or can I somehow list sub-scenarios (take off time, connecting flight) under the two main scenarios (fares)?

Main scenario 1: $300
 Sub Scenario 1a: 10AM
   Sub Scenario 1a1: Atlanta
   Sub Scenario 1a2: Denver
   Sub Scenario 1a3: Chicago
   Sub Scenario 1a4: Detroit
 Sub Scenario 1b: 2PM
   Sub Scenario 1a1: St. Louis
   Sub Scenario 1a2: Atlanta
   .....
Main scenario 2: $600
   .....

thomaskilian

  • Guest
Re: Use Case Descriptions
« Reply #12 on: July 10, 2004, 03:03:59 pm »
This is kind of GIGO (garbage in,garbage out). For what model would you take "Fly from A to B" as use case and within that use case model the tariffs as scenarios? I can't imagine a practical model, can you?

sargasso

  • EA Practitioner
  • ***
  • Posts: 1406
  • Karma: +1/-2
  • 10 COMFROM 30; 20 HALT; 30 ONSUB(50,90,10)
    • View Profile
Re: Use Case Descriptions
« Reply #13 on: July 11, 2004, 04:56:41 pm »
Quote
what is the fewest number of different scenarios I need to document for the following use case?


This depends entirely on the number of unresolved questions YOU have about the use case.

Quote
Use Case: One person taking Delta Airlines from San Diego to New York City


What's the context of the "system"?  Scheduling, revenue, W&B, routing, weather, fuel, res, checkin, baggage????  For the sake of a quick example, lets assume its baggage.

Possible questions/scenarios...

1. Pre-booked baggage
2. Accompanied baggage
3. Overweight baggage
4. Overdimension baggage

How is the system expected to behave in each of these situations?  Is it obvious? Does it need further explanantion or research?  Does a specific scenario present certain constraints on the design of the system?
Does the behaviour of the system under a specific scenario present complications that are best handled outside the scope of the automated part of the system?
Do you have ALL the answers to ALL the scenarios?  If so continue, if not go back to the business and explore the specific scenarios with them until ALL the answers are known and shared.

A scenario to me is NOT different examples of the SAME behaviour with different information variables.  A scenario is a description of the expected specific behavior of the system in a use case under a certain set of external conditions.  It is a way of exploring the expectations of the users - (who may expect or consider that these different behaviours are so bleedin' obvious that they didn't need to state them) in a structured manner - to get them to think about the different behaviours and explain them to you.  If the scenarios are "all the same behaviour" then there is no use in documenting more than one of them.

hth
Bruce
"It is not so expressed, but what of that?
'Twere good you do so much for charity."

Oh I forgot, we aren't doing him are we.

pchang

  • EA Novice
  • *
  • Posts: 4
  • Karma: +0/-0
    • View Profile
Re: Use Case Descriptions
« Reply #14 on: July 12, 2004, 08:10:01 am »
Thanks to sargasso and thomaskilian for their responses so far...

I guess my main question is, per quote from Captain_Ding_Dong:

>Should there be a number of different paths (branching,
>conditionals etc) possible through the use case, these
>are represented by a different senario.

So per my example of 2 x 3 x 4 = 24 branches, should I document all 24 scenarios using the UseCase -> Scenarios GUI dialog?

If yes, then the UseCase -> Scenarios GUI dialog seems to only support one level and does not support multiple levels of branches/conditionals (except for the numbering scheme "1.2.3.4" as suggested earlier).