Use Case Descriptions

[thomaskilian]

Hi again,
indeed the documentation support for scenarios in EA is a bit limited. So you are right in that respect that you have to use some kind of numbering scheme to indicate a level. If you are following the methodology described in this book http://www.usecasemodeling.com you have to do some editing after documentation.  (This is the way I do it.) However, the build in features in EA are good enough for most purposes and you can't serve everyone in the same good fashion.

Further I think that you did not fully understand the meaning of use cases In turn

A scenario is a description of the expected specific behavior of the system in a use case under a certain set of external conditions.

as Bruce pointed out leads to the question whether we are talking about the same thing regarding scenarios?

[sargasso]

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

Lets get a little pragmatically naive about this.
Per your example, without further ellucidation, I would presume that there is only ONE OUTCOME - the passenger arrives at NY City on some (Delta) aircraft that left at a designated time having paid a specific fare.  This is true regardless of the routing.
The fare amount and the routing and the departure time are values applicable to instance variables of the particular flight object.  From this viewpoint there is only one scenario - the object "passenger" is relocated from one location to another location at departure time (+flight time) and the value of their "wallet" variable is lightened to the extent of the fare paid.  Note also that the "route followed" attribute of the flight appears to have had no apparent bearing on this outcome.  Perhaps not, perhaps it has an influence on "flight time" - if and only if flight time is a derived value (somehow calculated each and every flight instance from the route).  However, this is a design issue not a use case issue.
Now being a suspicious sort of chap, I would question whether there is only one outcome.  Are there any realistic business conditions that could dictate different outcomes of the use case of interest to the system?  Lets see....
1. What is the outcome if the flight is cancelled?
2. What is the outcome if the flight is delayed on route?
3. What is the outcome if passenger wins the Delta 10millionth customer award?

Under scenario 1. the passener will not be relocated, under 2, the relocation time is changed (perhaps justifying the use of a derived flight time value!).  Is scenario 3 of interest?

Perhaps there is some misunderstanding of the abstraction level of scenarios here.  AFAI care, use case descriptions and scenarios tend more to the abstract side than the concrete instance example (unless there are good reasons to provide worked examples).  Consider the dreaded "Login" use case. "The system grants access to a user based on the correct validation of credentials.  If a user attempts three successive logins with incorrect credentials the user access account is locked and further access to the account will not be granted until a supervisor unlocks the account"

How many scenarios?

[1] Valid credentials presented on an unlocked account at attempt 1, 2 or 3. Outcome: access granted.
[2] Valid credentials presented on a locked account at  attempt 1, 2 or 3. Outcome: access denied.
[3] Invalid credentials on attempts 1, 2 and 3, account unlocked. Outcome: access denied and account locked.

Note that each of the above scenarios has a different outcome.  There are no duplicate outcomes dependent on user action or instance variable values.  Further note that "all the permutations" of valid credentials, account lock state and attempt number are not listed - as they have no bearing on the behaviour of the system nor on the outcomes.

hth
Bruce

p.s.  Today's competition: what's wrong with the above login description and scenario list?

[thomaskilian]

Hi Bruce,

p.s.  Today's competition: what's wrong with the above login description and scenario list?

my guess:
scenario 2 - if it is locked, you can't go through 2 and 3 since 1 is blocked already;
scenario 3 -  account locked, not unlocked

btw. What kind if job are you doing? Your answers are always so detailed that I wonder where you take the time.

[sargasso]

Thanks tk! Exactly what I was hoping to see - a different viewpoint from mine.

This, I hope illustrates why we do this and why a level of textual description is almost always necessary.

My "outstanding" question back to the users was "What is supposed to happen on (any) attempt number 4..."  The current scenarios are silent on this.  Now we also can ask the more general quiestion "What is the system supposed to do when a login on a locked account is attempted".

(I dont agree with your query on scenario 3 - its the way an account becomes locked).

So, although we are using one of the most so called "trivial" use cases it is easy to see how different viewpionts raise different issues - or sometimes the same issue in a more revealing light.  The presentation of a single (rugby) football with "User log in" written in it may not adequately explore the desired behaviour of the system.

However, note that this is an example used to prove a point not an exhortation to describe use cases to the nth degree.  You must use your judgement and knowledge of the human dynamics of specific project at hand to decide how detailed the documentation needs to be.  This, coupled with the business criticality of the use case will guide the need for "how much of this stuff do we need to write down".  The login for an ATM machine is obviously more critical than the login for access to the company online phone book maintenance utility.

Many years ago, last century in fact, when I was a young programmer of note, we used a plastic template and a pencil to "work out" the logic of parts of programs.  We did not do this for each and every piece of code - only the one that were difficult to describe, conceive or design.  There seems to be a misunderstanding that to be a true UMList you need to use every model/diagram/technique in every instance. I dont hold that this is necessary - all we need to be sure of is that we (stakeholders) are communicating and understanding properly.  UML is a convenient standardised notation to assist in this.

Sometimes I also get the impression that people think that "better UML design" will result in "better systems".  The truth is simply that "better design" results in better systems and UML is a technique that can assist in that goal.

Bruce

p.s.  I am a senior (as in older) project consultant, I do a lot of different work and at the moment am involved in a bit of detective work on an unstable J2EE/Oracle system.  This involves running test scripts over and over at various load levels attempting to find consistent failure "footprints" in the logs.  The runs are automated, I have got most of the log analysis automated and so have a fair amount of time while waiting for the next "crash".  Other times I do (development) process engineering, solution architecture, project risk management, blah blah blah...  However, I am shortly going to run out of work at this client and wil be back on the job hunting again so the "detailed" answers (aka raves) may well dissappear.  

[ulb]

Hi everybody

Very interesting discussion!  

IMHO scenarios has to be modeled as UC extentions.
So you can see it graphicaly, how many scenarios you have an what are the conditions to get into one scenario.

Am I right?  :-/

Cheers..

[angel-o-sphere]

Hi,

unfortunatly you are not right

A Scenario is like an Object and a Use Case is like a Class.

An object does not extend a class .... but is created with a "new statement" from the "template" that is describing this class.

Suppose you have an use case and an activity diagram describing that use case. Suppose that activity diagram has some descissions and more than one end point.

Every single way from the start to an end (choosing the one or the other way at every descission), that are the possible scenarios. Some might not be meaningfull ... or realistic. To be a true scenario you need to make  a list of executed activities including sample data. (Why did you choose a certain path at a certain descission? Because your sample data forced you to do so!)

Often it is more conveniant to describe scenarios with sequence diagrams.

angel'o'sphere

[thomaskilian]

Hi Bruce,
I was off for vacation. Hope your client still pays you for  bug watch I always enjoy your raves  

[ceatley]

This has been a very interesting subject to read.   If any one is interested there is a new book published by OMG Press that supports most of what was discussed here.  
It is:

UML 2 Toolkit
Wiley Publishing, Inc  (At least in the USA and Canada)
ISBN 0-471-46361-2

I think the group will find it interesting.

[bakerbr]

Hi,

I know Kurt and Ian personally. In fact I was one of the reviewers for their book. I have read many many books on use-case modelling and this one is absolutely the best. Even Ivar Jacobson has made that same bold statement.

I'd like to take the opportunity to explain some of the thinking behind the style they have chosen. At the end of this overly long blurb I have listed a tool we use that supports Kurt’s and Ian’s style for authoring use cases.

The best way to explain the style is to first explain some of the problems inherent with many use-case models….

Communication is the primary intent of the style. In practice, bolding the glossary terms is an excellent communication strategy and if you take the time to do it you can simplify the flows of events by making proper use of the glossary. For example, you can relegate descriptions of data fields to the glossary and thereby reduce the amount of text in the use case dramatically. The bolded term tells the reader to go to the glossary for the detail. Practically though, it needs to maintained manually and relies on the discipline of the analyst.

One of the biggest problems with use cases is the amount of internal cross-referencing. Use cases errors often come to pass when a step is inserted into a flow. This can break references from alternate flows. There are some tricks with Word you can use to get around this (bookmarks and cross references) but they are not foolproof. The idea behind the extension point is to create a floating label that can be referenced. This label is impervious to steps being inserted or removed. The label is also useful for creating extension use cases. The extending use case references the floating label and therefore decreases the coupling between the extended and extending use cases - which results in fewer errors in the requirements.

The idea behind use-case scenarios is that reading a use case from start to finish is a near impossible task for anyone but the author. The reason for this is that each flow - when read in isolation - lacks context. By listing the flows that make up a scenario you are enabling the reader to read a path through the use case. Using scenarios also promotes iterative development because you can prioritise the use case development by scenarios. These scenarios align very nicely to business value. Your developers also have a story that they can implement. Your testers have the basis for their test cases. At the end of the iteration you have implemented and tested a complete path through the use case. (This is where FDD has got it all wrong - but that should be the subject of another thread.)

Finally, use cases are primarily a text-based artifact. In the vast majority of cases the flows of events are written with Microsoft Word. The UML has added certain semantics to use cases (include, extend, generalization) that simply do not work in a document-based paradigm. If you structure your model according to how the UML lets you, you end up with a fragmented description of the system's behavior and a nightmare to implement. If you are using Microsoft Word to write your use cases then you must take care that you do not overuse the modeling features the UML provides you with. The problems that are cause by over structuring a use-case model is NEVER felt by the author. It is all the consumers of the use case that suffer badly.

As for whether I use this style - absolutely. All our customers love it. I would be happy to share experiences with anyone who would like to contact me directly.

There is a tool out there called Use Case Studio (www.rewrittensoftware.com). It implements Kurt's and Ian's style. Unlike Word it understands the UML and has full support for included or extension use cases. This means you no longer have a paper chase on your hands when you have a structured model. It also has a neat feature called a Scenario Builder. The Scenario Builder allows you to filter out all flows that are not part of a scenario. This means your use case can be read like a story from start to finish.

I hope this helps.

Regards,

Bryon
Empulsys
www.empulsys.com

[Kevin Brennan]

I've actually tried out the tool Byron mentions. It has some nice features but ultimately I ended up retreating to EA/Word.

I have two major complaints with it; it can only handle requirements expressed in use case form (no tables, etc.) and it can't generate a full report of all elements in a requirements package. You have to do it one UC at a time.

These two things make it not especially useful for me right now, as a document of some sort is and will continue to be the way my business stakeholders and developers prefer to get their information.

Now, if this tool could integrate and extend EA, replacing it's use case dialogs--then I would have an almost perfect tool when the two were combined. (I use EA exclusively for analysis, so the code generation and reading features have little value to me, though I recognize such things are a major selling point to others).

On the Bittner/Spence approach--it's not a bad one. I initially adopted Cockburn's method for writing use cases, but I found that business stakeholders especially found the resulting documentation hard to follow (developers were usually OK with it). Scenarios really need to be made explicit and alternate flows fenced off properly for a business audience.

[jonespm]

Hi,

I've tried, without success, to get a copy Bittner and Spear's Use Case Modeling in Australia. Can anyone provide a lead - I don't want to put in on an 8 weeks back order at Dymocks.

TIA - Peter

[bakerbr]

You do not mention where you are located. I have seen it on numerous occasions at the Technical Bookshop in Melbourne and Angus & Robertson in the city (Melbourne).

[jonespm]

Hi,

I'm in Adelaide - both Dymocks and A&R tell me they would have to bring it from the States.

Peter