Recording detailed use case

[weblander]

I've just been looking around at how to make detailed use cases with EA. I'm able to add scenarios to the use case which goes some of the way with basic path etc but I was hoping to have a more structured way of enetering this information with the steps of the basic path numbered and with sub steps etc.

Is there anyway to do this within EA or am I forced to restort to word for this level of detail?

Cheers

+Steve

[«Midnight»]

I gather you want something more definitive, identifying the steps as something other than 'just' text with embedded numbers (or something) to show which step is which.

You can add an associated diagram, which can be an Activity Diagram, State Chart, or one of several other types. This would allow you to illustrate the steps in the use case in a clearer manner.

Don't quite know if that helps. Let me know.

[thomaskilian]

Writing Use Cases (as suggested by Cockburn, Bittner, et al.) with EA is a bit limited. You can use the scenarios to write most of the text. But formatting is only possible by handwritten HTML or Wiki-like style. Another (often used) way is to place the scenarios in a Word document or (as being possible recently) in a linked document. I adopted a mixture of the above and what ICONIX is using for writing Use Cases.

[kevincam]

Yeah it would be nice to have at least bullets and auto-numbering of the steps in the scenario.

[nara_c]

... Another (often used) way is to place the scenarios in a Word document or (as being possible recently) in a linked document....

I follow a similar approach as suggested here.  I created a custom Linked document template with the place holders for the various Use case description sections that we use.  The within the EA properties box I only specify the name and a brief description in the Notes field.  For the rest of the description including scenarios, I use the Linked document.  

To print out the details I ensure that the RTF template I use has the "model document" option ticked so that the linked document is displayed with formatting and all.  This has worked well for me and my team.

One caution though is that if you use EA even for documenting and maintaining your test scenarios, you will not have the ability to import the scenario steps since they are not in the use case property but rather in a linked document.

Another hint which I found useful for documenting detailed Use cases is to use named flows instead of numbers.  This way instead of referencing a number in an alternate flow or other use case (such as at step 5 of Basic flow), I mention the location of the flow (such as at [request customer details] of basic flow).  The obvious advantage of this is that in case I introduce an extra step in the flow during use case review then I will not need to renumber all the referenced location since the name remains the same.

Hope this helps.

[weblander]

Thank you everyone for all your responses - even though it confirmed my suspicions.

Thank you also for the suggestions. I'm not sure which way we are going at the moment - probably in word and then creating the link - at this stage I don't know as we are moving more on to state diagrams and class diagrams etc which is more solid ground for me and where EA shines more.

It is a shame EA doesn't support detailed use cases as per Writing Use Cases. Although your suggestions may help in some way I would still favour direct built in support for detailed use cases as I personally feel it would add even more value to an already exceptional product.

Once again. Thank you all for your help (and prompt as well) and suggestions for work arounds.

Cheers

+Steve

[«Midnight»]

Steve,

This is really worth requesting as a feature. Use the Help / On-line Resources / Request a Feature menu choice from within EA. This gets the request right into the Sparx hopper, and they take these requests seriously.

David

[jeshaw2]

Another hint which I found useful for documenting detailed Use cases is to use named flows instead of numbers.  This way instead of referencing a number in an alternate flow or other use case (such as at step 5 of Basic flow), I mention the location of the flow (such as at [request customer details] of basic flow).  The obvious advantage of this is that in case I introduce an extra step in the flow during use case review then I will not need to renumber all the referenced location since the name remains the same.

I really like this idea.  Can you expand a bit on how you form and place a flow's name?  Perhaps two or three lines to demonstrate the technique?

Thanks

[TrtnJohn]

I think EA has adopted more of the ICONIX view of use case text and not the Cockburn implementation.  If would be nice if there was an option to describe your Use Cases either way.  Plus, EA could automatically manage your path numbering and such for Cockburn style uses.  This would be a big plus.

[thomaskilian]

I really like this idea.  Can you expand a bit on how you form and place a flow's name?  Perhaps two or three lines to demonstrate the technique?

Thanks

Jim,
it's just like nara_c wrote. Place labels like [perform login] at any meaningful location in the UC scenario. Then you can write the extension separately. Inside the extension you can specify something like "resume at [perform login]" or "The UC ends here". Your UC might look like Pseudo Code afterwards and it might also result in spaghetti pseudo code (or pseudo spaghetti code)

[nara_c]

Jim,
it's just like nara_c wrote. Place labels like [perform login] at any meaningful location in the UC scenario. Then you can write the extension separately. Inside the extension you can specify something like "resume at [perform login]" or "The UC ends here". Your UC might look like Pseudo Code afterwards and it might also result in spaghetti pseudo code (or pseudo spaghetti code)

Actually that is not what I meant it.  You seem to refer to use of placeholders to indicate includes use cases or subflows.  I meant using named steps instead of numbered steps.  In fact I avoid psuedo code kind use cases descriptions since they are difficult to follow.  I prefer to select one path as the happy day scenario with no conditional flows and add all other flows as alternate scenarios.

Jim, in response to your request, here is an example based  on an example use case from Rational. ( I have added the example text in Blue to differentiate from my comments)


--- Use Case description follows ---
1.    Brief Description
This use case allows a professor to select the course offerings (date- and time- specific courses will be given) from the course catalog for the courses that he/she is eligible for and wishes to teach in the upcoming semester.

The actor starting this use case is the Professor. The Course Catalog System is an actor within the use case.

2.    Flow of Events
The use case begins when the professor selects the "select courses to teach" activity from the Main Form.

2.1     Basic Flow – Select Courses to Teach

[Display list of courses]
* The system retrieves and displays the list of course offerings the professor is eligible to teach for the current semester. The system also retrieves and displays the list of courses the professor has previously selected to teach.

* The professor selects and/or de-selects the course offerings that he/she wishes to teach for the upcoming semester.

* The system removes the professor from teaching the de-selected course offerings.

[Validate selection]
* The system verifies that the selected offerings do not conflict (i.e., have the same dates and times) with each other or any offerings the professor has previously signed up to teach. If there is no conflict, the system updates the course offering information for each offering the professor selects.

2.2     Alternative Flows

2.2.1    No Courses Available
At [Display list of courses] if the professor is not eligible to teach any courses in the upcoming semester the system will display an error message. The professor acknowledges the message and the use case ends.

--- end of use case ---


Now the advantage of this is that, I do not need to add named steps for each part of the flow.   In case on further analysis I discover other alternate flows are possible from other steps I can include a named step there and use that in the alternate flow.

for e.g.  in the above illustration, say the system has to be built to warn the professor if they have removed all courses thus having no courses to teach in the next semester.  To include this in the description all I need to do is first include a named step in step 2 above as shown


[Professor makes selection]  
* The professor selects and/or de-selects the course offerings that he/she wishes to teach for the upcoming semester.

Then I add another alternate step


2.2.2 All courses removed
At [Professor makes selection]  if the proferssor has removed/deselected all courses that he or she is offering thus resulting in no courses being on offer, the system should display a warning and request confirmation before proceeding.


The real advantage with this approach is when a new step is introduced early in the use case flow.  In the numbered steps approach traditionally used this would result in renumbering all the steps and thus updating the reference numbers in other locations such as alternate flows.  
This is a situation that often occurs since as we all expereinced use cases continue to grow as the system is developed or refined.

Hope this explanation helps and you find this approach useful.

Cheers

[TrtnJohn]

nara_c,

I like this notation.  Although I don't see how you could possiblke keep out resume logic like Jim was describing.  For example, what would you do if your alternate path prompted for the option to abort or continue?  You must add some text to describe some resume back to the basic path if the professor selected continue...

[TrtnJohn]

I just realized a few more questions:

What do you do with alternate paths that get somewhat involved?  Do you name steps here as well?  What about alternate paths that actually have their own alternates?

[nara_c]

nara_c,

I like this notation.  Although I don't see how you could possiblke keep out resume logic like Jim was describing.  For example, what would you do if your alternate path prompted for the option to abort or continue?  You must add some text to describe some resume back to the basic path if the professor selected continue...

You are correct.  In provided a very basic example where I focussed on explaining the named steps concept.  As a result, I missed a very import step in the Alternate flow definition (i.e.) stating to which point it would return.  Here is the relevant flows of the revised example, in an attempt to clarify further.

2.2.2 All courses removed - Confirmed

At [Professor makes selection]  the professor has removed/deselected all courses that he or she is offering thus resulting in no courses being on offer.

*The system displays a warning and requests confirmation that the professor is not teaching any courses for the semester.

*The Professor confirms that they will not be taking any courses.

*The system records the changes and the use cases ends.



Note how the description of the alternate flow indicates the point at which it enters this flow from the main flow.  I prefer to use bullet points for each step of the alternate flow instead of named steps initially as I describe the use case.  

I just realized a few more questions:

What do you do with alternate paths that get somewhat involved?  Do you name steps here as well?  What about alternate paths that actually have their own alternates?

In response to this, I do not normally run into too many situations where alternate flows have other alternates.  Having said that, in the above example, the professor could have removed all courses by accident and then rejected his choice in the confirmation step.

So going back to my ealier advantage of the named flows method, I could then name the step in the alternate flow where the system prompts the professor as [System prompts for confirmation] and create a new Alternate flow as follows.

2.2.3 All courses removed - Not confirmed

After [System prompts for confirmation] in alternate flow 'All courses removed - Confirmed' if the professor does not confirm the action the following flows occur.

*The Professor rejects the changes since they will be taking courses.

*The system rejects the changes and returns to [Display list of courses] in 'Basic Flow - Select Courses to teach'.



Note the flexibility of this approach as opposed to the numbered steps approach where if you used numbers instead of names you may have to constantly be renumbering to point to correct points.

It is important to also note that the focus of this approach is to replace numbered steps with named steps.  I beleive it will work with any style of use case documentation that you prefer.  Personally I do not like to have psuedo code like steps in a single flow and hence break them up into multiple discrete steps.  Tends to make for a longer use case desciption, but given that non-technical end users are often the target audience of the use cases this is less confusing.

Hope this helps.

[jeshaw2]

Is everyone aware that MS Word has the ability to insert references to numbered paragraphs?  If the referenced paragraph is renumbered for any reason, Word will automatically update all references to it.

Given this feature of Word, I'm not sure of the value of Named Flows...?