image
image

Articles

 How to Write Use Cases
09.08.11


A previous IRM paper - How to use Use Cases - highlighted the need for clear and logical thinking when documenting the primary and alternate flows of a use case. A use case diagram is all well and good for communicating the scope of a particular event but to explain what’s happening inside the use case we need to revert back to a textual description.

The How to use Use Cases paper described a relatively simple event – a student registering for a course. Whilst the primary flow had 5 steps, the alternate flow in the formal (fully specified) use case involved 9 steps each comprising 3 or 4 interactions. The line by line description of the alternate flow ran to one full side of A4 paper and quickly became an exercise in concentration! So how else could we write it?

Before you reach for one of the freely available use case templates, take a moment to consider who’ll be reading your finished description. Developers want as much details as possible (for which a template is ideal) whilst business users want to be able to intuitively grasp the essence of what you’re communicating. To do this we can still employ a use case framework, but populate it with business, not technical, language. Here are three popular techniques for doing this:

Narrative – good for simple events or for giving an overview description of the use case at the start of the project. A narrative use case should describe the actor, system, actions performed, the purpose of the use case (objective) and how it will be met.

Loyalty Cards are being introduced for existing and potential customers. Any customer can apply for a Loyalty Card to use in any retail branch. On presenting the card they will receive a 10% discount. If an item is on sale then the discount is reduced to 5% of the sale price. Customers can use their cards when shopping online and get the same discount. They can also use their Loyalty Card to participate in regular promotions and competitions. Loyalty Card benefits for promotions and competitions will be set by the promotion/competition product line manager.


Note that this narrative example also contains a number of business rules embedded within it. Narrative style is intentionally brief so as not to intimidate the user – it’s intended to provide the context for the use case. Narrative style becomes considerably harder to write (and understand) for complex or detailed requirements.

Scenarios – these describe a flow as a series of numbered steps. Each step is a single sentence describing what happens next. A scenario describes a flow from the user’s perspective but can get difficult to follow as the number of steps increase.

3a: Student selects Create a Schedule
  1. The System checks that the Student does not already have a Schedule for the upcoming semester.
  2. The Student selects 4 primary course offerings and submits their selections.
  3. The System checks that the prerequisites are satisfied and adds the courses to the Schedule.
  4. The System generates charges associated with the selections made.
  5. The use case resumes at step 4 (of Primary flow).
3a.1a: Student has an existing Schedule
  1. The System displays error “Student has an existing Schedule” and cannot create a new one.
  2. The use case resumes at step 2 (of the primary flow)
3a.3a: Prerequisites not satisfied
  1. The……….
  2. ………etc.


Using a unique numbering system allows each step to be cross referenced in a requirements traceability matrix. This makes it easier to ensure that every requirement is captured and later tested. Scenarios are good for a general description of a flow but once they get complex, use models as well (e.g. an activity diagram with swim lanes) for easier communications both with users and developers.

Dialogue – is a popular technique for describing a flow and like a scenario, it describes the flow as a series of steps. The steps however are horizontal rather than vertical, as in the following example of an online purchase.

1 - Customer logs on to retail website
3 - Customer specifies search criteria for goods
5 - Customer selects items detailed description
7 - Customer selects item for purchase
9 - Customer goes to checkout
11 - Customer chooses to pay by credit card
13 - Customer enters loyalty card details
15 - Customer submits order
17 - Customer logs off
 		2 - System acknowledges customer profile
4 - System lists goods meeting search criteria
6 - System provides detailed description
8 - System adds goods to shopping basket
10 - System displays shopping basket list
12 - System adds credit card details to order
14 - System displays loyalty discount
16 - System confirms order and sends receipt
18 - System closes session


Dialogue is a particularly useful style when there is continuous two-way interaction between the actor and the system. The actor does something, the system responds, the actor then does something else….etc. Not every step of the flow is shown - in step 8 for example the system might perform a number of actions such as check stock level, calculate shipping cost, etc., before returning a response to the actor. When using a dialogue style, only the interactions between the actor and system are shown.

Whatever style you use, remember that use cases are tools for communicating. A well written use case is like a good story, enjoyable for the author to write and enjoyable for the user to read. Everybody likes a good story with plenty of pictures, a hero, a good plot and a happy ending!




return to white paper & articles menu image


 image
image