The best way to write use cases?

[mbc]

Dilemma:
Write long scenarios in one use case, or split explicitly into several use cases using include and extend relationships?

Craig Larman ("Applying UML and Patterns") recommends the first while Constantine & Lockwood (www.foruse.com) advocates the second approach. What are your opinions on this?

These are the points I have noted for myself:

Pros for long use cases:
1. Easy and quick brainstorming process
2. Can be on a higher level of abstraction from the user interface implementation.

Cons for long use cases:
3. Causes duplicate use case
4. Does not give a complete picture
5. Sequential description. Normally users have many choices in the order in which they carry out actions

Pros for include and extend:
6. Gives a complete picture of the use of the application (when all use cases are complete.

Cons for include and extend:
7. Forces early decisions on user interface design.
8. Not easily readable for people without knowledge of use case diagrams.
9. Not easily writable for people without knowledge of use case diagrams.

What is the best? I am leaning towards avoiding too many include/extend relationships and trying to capture typical use scenarios instead of trying to create a diagram of the whole user interface at once. I focus on reasons 1, 2, 7, and 8.

Hope to start a discussion that will give me more insight!

Mikkel

[CJ]

G'day Mikkel,

I think this is one of those questions that leads to an "It depends..." answer.

Personally, I prefer the divide and conquer approach to anything.  Divide things up into as small a bite size as possible without getting to the point of losing value.

I've found that users and/or user representatives don't do too well with diagrams.  So very simple context diagrams for them, and a bigger focus on use cases (the text form) that merge includes/extends if it makes things easier.  I don't think most users like to have to bounce back and forth between documents to figure out the full picture.

For the technical crew who are used to diagrams, then break things down to the max.  That said, I think it's best to limit diagrams to between 7 and 12 objects to keep them clean and simple.  Better to have many diagrams focusing on different aspects/subjects/contexts/etc ... going from overall big picture diagrams to very detailed and specific diagrams.

Really, it all depends...

[Steve_Straley]

Mikkel,

I want to echo Jason's comments; however, having said that, I tend to lean to many UC's.   To me, there are a couple of reasons.

First, the point about "causes duplicate use cases" can easily extend to class structures.  I know I want to abstract down classes to manageable segments and thus avoid duplicate code.   If that is good for code, why can't it be good for the models describing the behavior of that code?

Second, I like to think of UC's in terms of testing.  In other words, QA is going to rely on the UC's to develop test scripts.  Again, if a UC is broken down and can be "re-used", then the test script can be "re-used" and not duplicated.   Of course, there is a balance... the test must have enough information to come to a proper resolution.   Too little and the test is meaningless; too much and the test itself gets complicated.

So there is a balance and as I said, I agree with Jason.  Striking that balance can be complicated.  For example, I just completed a UML set with 203 UC's, 1060+ steps, and over 60 actors.   With this complexity already built into the system, I tried to make the testing and readability of the UC's the primary focus.

Just my .02...

Steve

[mbc]

Jason and Steve, thanks for the quick replies. I wasn't wrong, when I thought my question could bring out some interesting points and opinions.

I am working on a quite small system, and maybe what I refer to as few use cases are actually detailed use cases to you.

"If that is good for code, why can't it be good for the models describing the behavior of that code?"
Because it requires that design decisions about the code are made already during requirements analysis. That, is the only objection I have to that.

Does any of you have any examples of use cases or links that illustrate what you consider large and small use cases?

Mikkel

[Steve_Straley]

Mikkel,

Perhaps I didn't phrase myself correctly last time.   When I made the comparison to code versus design, I was trying to imply that we here don't like to duplicate code and that philosophy is carried over in the design phase along with the UC's.   That's all.

Steve

[Ilja Kraval]

I think (it is conclusion from praxis), that the right approach lies in these two points:

1. if it exists co-used (re-used) use case, we must make interaction: extends, include or gen.-spec. and "point out" the co-used use case  

2. we can make interaction ("point out") in some long use cases, when it is more transparent than without it

It is the same question like "calling functions" in structural programming.

Ilja Kraval

[jaimeglz]

Hi all,

Just want to contribute another two --well, really four-- bits:

1. Ilja's point on reusability goes to the heart of the matter when dealing with <<include>>, because the most iportant reason to do an <<include>> is to have a sequence of events that can be reused by several use cases. Example: "update budget" or "update GL" use cases can be quite useful to <<include>> in order to represent interfaces to accounting (and they can even be reused among different projects and applications).

2. <<extend>> is a different matter, because it is used for conditional or exceptional event sequences (user choices, error messages, system not available, and so forth...). These are sometimes reusable (the user chooses a certain menu item), or not (an error message in a particular window or screen).

3. Your use case diagrams are getting too convoluted, and are not adequate for discussions with users? I suggest doing process diagrams (which are extensions of activity diagrams), as the best way to explain to users what you are trying to depict. Yes, use case analysis is very much object oriented, and oftentimes it is not as user-friendly as we wish it was.

4. You have a ton of scenarios, and they horribly complicate a diagram or a use case? I suggest creating a special diagram where the scenarios are represented as individual use cases, linked with a generalization relationship towards the most general use case (the basic path, that is). This basic path is practically the only one you will use in your other use case diagrams. This is a very strict logical approach: the basic path should contain only the most general sequence of events.

If you find that something works for your project and saves a lot of time, please send my above comments to the "formal, but not that useful" dept.

Jaime Gonzalez

[PhilR]

Hi Mikkel,

I bet you knew this would spark a lively discussion when you made the post ;-)

I can't resist my 2 cents either.

I teach use case modelling and find that people who are just beginning to use use cases should stay clear of extend, include and generalise.  Too confusing.  Especially if you read the official UML stuff complete with extension points and so on.

Mnay developers turned analysts carry over their desire to decompose and remove the redundancy from everything they ceate.  The result is a gizillion use cases that often smell of functional decomposition.

Redundancy is a problem when you have to maintain use cases as requirements evolve.  In fact I find that for me this is the most pressing driver for breaking up a use case.

Finally, why can't the tool switch between the two views.  I create a use case model complete with extends and includes but when I decide to print it out for the users to review the top-level use case is fully expanded by physically including the text of included use case etc.

[mbc]

Phil,

yes, I expected (and hoped for!) a lively discussion. And so far I have not been disappointed.

Your point about developers doing functional decomposition already in the use case stage is exactly the cause of my scepticism about breaking use cases down too much.

All that is needed to do what you require of the tool, is a documentation generator that is a little more flexible. I have some plans in my head about implementing something that works through the EA automation interface, but I can't promise that I'll ever have the time to finish it.

And I would like to add another question to this topic:
What about when the user interface design is part of the project? How do you avoid making design decisions in the use cases, when scenarios often sound like "step 117: User clicks the GO button". My approach to this, at the moment, is to write a set of less detailed use cases before user interface design and then refine them by incorporating user interface details before moving on to the design model.

I am eagerly awaiting more posts, although I wont be checking the forum as much the next 2 weeks due to travelling.

Best regards
Mikkel

[Ilja Kraval]

Hi,

… of course, jaime, you are right with describing of purpose <<extend>> and I agree with this comments .

I wanted to show necessity and due when interaction is unavoidable. It is possible, that inside <<extend>> is hidden re-use, in addition, and maybe not. When re-use is found, we must point out use case as necessity and it is like “model error” not to do it. Every re-used model element (not only use case) must stand alone for re-use (for interactions), and it cannot be “hidden” inside another element as part of comment or as part of scenario etc., (= effect of “Clipboard Copying Mistake”).

I think, when we see <<extend>> and it is not re-used use case and we don’t model it as interaction, it is incorrect, of course, but it is not “fatal model error”. It is only inaccuracy.

See this example of scenario:
-----------
Use Case “A”, scenario:
…
User selects item from list of <something>.
If item of <something> does not exist, User can add new <something> (see Use Case “Adding new <something>”)...
-----------
It is <<extend>> interaction. Use case “Adding new <something>” can be “called” from use case “A” in extension point with condition "item not in list" and interaction is: “UC Adding new <something> extends UC A”. Specially at this case we must model it as “stand alone element” (as necessity), because use case of adding is re-used from other points of application. For instance User can use “Adding new <something>” naturally as “start dialog” (= not as part of another use case) and start event of dialog in business environment is “user wants to add new <something>”.

On the other hand, in the case, that the part of scenario <<extend>> is not re-used, it is not so strong necessary to point it out and make <<extend>>. It is only more correct to do it, because then we can see structure of scenario better in diagram as picture and not only in long text.

Ilja Kraval

[PhilR]

Mikkel

All that is needed to do what you require of the tool, is a documentation generator that is a little more flexible. I have some plans in my head about implementing something that works through the EA automation interface, but I can't promise that I'll ever have the time to finish it.

You could create a stereotype use case of "internal" or something like that.  Use this stereotype to decompose use cases to everyone's satisfaction and then expand the decomposition in the text as you suggest.

Only problem.  EA does not display use case stereotype text in the use case symbol.  However, it will display any metafile image that you define for the stereotype.

What will the symbol for an internal use case look like?

Phil

[CJ]

G'day,

Symbols for use cases?  My knee-jerk vote would be for the ones Alistair C.o.c.k.b.u.r.n. used in "Writing Effective Use Cases".

[Fintan]

What about when the user interface design is part of the project?

How do you avoid making design decisions in the use cases, when scenarios often sound like "step 117: User clicks the GO button".

Hi Mikkel,

I would NEVER write a scenario like the above which has - as you point out - a UI design decision already made.   I would reword this as something a lot more specific (rather then general).  I.E. "Step 117: Bank Clerk chooses to run the account reversal transaction".  This step will most probably be coded as the user clicking a GO button, but the use case does not have to describe that.

Remember the point of the use case is to show that the system does something of use to the Actor.  Choosing to run a useful function of the system is a goal of the Actor - clicking a button labelled 'GO' is not IMHO.

Once the use cases have been written the UI design and the Analysis & Design (for code) can be run in parallel - both using the same use cases as their launching points.  In fact test cases can be started as well.  UI design will focus on screens and navigation between them.  Analysis & Design will focus on objects and classes and the relationships between classes.

In Summary :
I avoid the word 'user' in use case texts and always specify the actor name.

I never use "the <<actor name>> clicks OK button", instead I write "<<Actor name>> chooses <<particular function of system>>.

Use Cases should be design agnostic, UI agnostic and contain all data elements required.

Once a use case like this has been written and approved, 3 different teams can start building based on the use case.  
1 - Analysis & Design.
2 - UI Design
3 - Test cases
(Perhaps 4 - User documentation?)

Each of these 3 are likely to discover items which should have been included in the use cases, so running these in parallel will solidify the use case in the least amount of time.

Regards,

Fintan

[Fernando Esposito]

Hi,

Take a look at this book:

"Writing effective use cases" by Alistair Cockburn.

The best I've ever read.

Lots of invaluable recomendations and a solid methodological foundation.

[Fernando Esposito]

Ooops

I didn't know about this funny thing.

Alistair C-o-c-kburn

Hi,

Take a look at this book:

"Writing effective use cases" by Alistair Cockburn.

The best I've ever read.

Lots of invaluable recomendations and a solid methodological foundation.