Use Cases Not All Things to All People

Author: Geri Schneider Winters

An interesting question came up in another forum, and I would like to address it here because I think it is a common one.

I am currently struggling introducing use cases into a large product development organization and a prime obstacle I am facing is that one use case should be all sort of things to different people. For Product Managers it should be dead simple focusing on high-level application functionality and scenarios (probably close to user stories), for the Developer it should be much more detailed and written with great rigor (scenarios described with activity diagrams); not to mention the Usability team who see use cases as Alan Cooper in About Face. I am wondering how to address all this. In architecture we came up with the View Points. I am wondering which way is better: (a) providing different perspectives on one use case by filtering some portion of its description, or (b) deriving more detailed use cases from one higher-level use case. Although it may lead to duplication, I intuitively bend towards solution (b). It provides better separation of concern. Any thoughts on this?

I think use cases are a wonderful tool. I have been using them, writing about them, teaching them to other people since sometime in 1996. But they are only one tool in my toolbox.

I think of it this way – a use case is not a kind of information, it is a form of information, a template, a way of structuring information. If you are describing a process, a procedure, a sequence of steps, then a use case works very well. But other forms may be better at describing your information. A use case is a poor choice for sequences with a lot of decision points (for example). In that case, I would look at activity diagrams, flow charts, or state machines to describe the information.

When choosing the form I will put my information/requirements into, I think about the information itself (as I just described), but also the people who will consume the information and what form will make it easier for them to consume it. When I was working on an embedded system with a bunch of electrical engineers, I used a lot more state charts, which I do not use at all with my IT business stakeholders. There is nothing wrong with producing the same information in different forms – user stories for the project sponsor, state machines for the engineers, for example.

While use cases started out as a way to describe telephone switching networks (see Jacobson’s early work in the 70’s for example), they have become a tool for describing user driven behavior. I have used them for embedded systems, but in that case, you really need to be careful about what is driving the system. It is very likely not a person, so the use case should be focusing on the actor/thing that is driving the process/behavior of the system. That may be hardware or another system, or even a clock.

So the answer to the question is, figure out the best form of information for each audience and create the appropriate documentation/diagrams/whatever. Just like the different Architectural Views Ponits, we have different views of requirements for different audiences, and those different views will probably not all be use cases.

What kinds of forms have you used for presenting requirements to different audiences? Do you write use cases for everything? Do you maintain different versions of the use cases for different audiences? Or do you maintain your requirements in different forms – user stories, use cases, sequence diagrams, state diagrams, flow charts – for different purposes?

Use Cases Are Not the Only Requirements

Author: Geri Schneider Winters

With all the focus on Use Cases, it can be easy to forget that they are not the only kind of requirements. Use Cases are very good for some kinds of requirements, but really bad for other kinds of requirements. One of our challenges as Business Analysts is to determine the right way to document the requirements for a particular project.

When starting on a new project, one of the first things I want to find out is “Who or what is driving the requirements for this project?”. I was really reminded of this when I read Richard Denney’s book “Succeeding With Use Cases: Working Smart to Deliver Quality”, a book I highly recommend.

If the project is being driven by changes in processes, then Use Cases probably make a lot of sense, since they are good at describing processes. But you could also use User Stories, Scenarios, Flow Charts, or Test Cases to describe processes. Which you choose will depend on corporate culture and the software development process that is used on your project.

In this case, find out what is driving the process change. If the process change is coming from the way that people work, then you can find requirements by talking to the people or watching them work. If the process change is coming from a technology change, then you may need to start working on the requirements by learning about the new technology. I worked on one project which was to design software to run on hardware that tested IC chips. The source of my requirements was the tests that had to be run on the IC chips. I documented those tests as Use Cases because that is what the customer wanted me to use for requirements.

If the project is purely a change in underlying technology, then a lot of your requirements will be the non-functional requirements (often called FURPS). You might have to write these requirements as formal “Shall” statements. Look over a template for a Supplementary Specification for ideas of the kinds of requirements you might need.

For example, if I am installing COTS (commercial off-the-shelf) software, then I do not need Use Cases for how the software works. I might need Use Cases for how we will use the software in our company, if that information is not obvious. But I really need to know other kinds of information, such as how many users will use it at a time, what response is required, how many transactions per second it will have to handle, how many records will it have to store and process, and what kind of security is required to use it. I will have to talk with the folks in Enterprise Architecture to find any restrictions on where or how it can be installed. There may be a need for a new server, so I have to find out the contraints such as what platforms are allowed, or how much money we can spend on it.

In embedded systems, you may find that truth tables or state machines do the best job of describing the requirements. In this case, there is probably no human interaction, and the processes are all closely related to the hardware and how it works. A truth table or state machine is a good way to describe the different states of the system and how it is allowed to change.

Here are some ideas for kinds of things I have seen used (successfully) as requirements for different kinds of projects. Consider these to see if they are appropriate for your projects:

  • Use Cases
  • Shall requirements
  • Test Cases
  • User Stories
  • Scenarios
  • User interface designs
  • FURPS requirements
  • Prototypes
  • Flow charts
  • Activity Diagrams
  • State Machines
  • Truth Tables

 

How do you decide what kinds of things to use for requirements on your projects?

What other kinds of things have you used for requirements for your projects?

 

Alternatives of Alternatives

Author: Geri Schneider Winters

Another great question came from Adesh Sharma about whether or not he could write alternatives to alternatives in use cases.

There is no actual standard for the formatting of a use case, just guidelines and best practices. Your primary goal in writing use cases is communication. No matter how you structure a use case, if the readers do not understand it, then you need to change the use case.

In some cases, you will find that describing an alternative of an alternative makes a lot of sense, and actually improves the readability of the use case. In other cases, the use case will be more confusing.

Here is an example I created specifically to show the use of an alternative to an alternative. I think in this case it reads OK, and may be a reasonable way to document this use case.

Place Order Use Case
Basic Flow of Events
=====================

1. The use case begins when the customer selects Place Order in the order processing software.

2. The order processing software displays an order form to the customer.

3. The customer enters his or her customer id into the order form. If the customer does not have a customer id, go to the alternative “The Customer does not have a customer id”, which is shown below.

4. The system uses the customer id to get the customer’s account information from the customer database.

5. The system displays the customer’s name and shipping address on the order form.

6. The customer enters a product code into the order form.

7. The system uses the product code to get the product description and price from the product database.

8. The system displays a description and price for the product on the order form.

9. The order form adds the price to the order total.

10. The customer enters credit card payment information into the order form.

11. The customer selects the Submit button on the order form.

12. The order form sends the information entered by the customer to the order processing software.

13. The order processing software verifies the information from the order form.

14. The order processing software saves the order as pending in the database.

15. The order processing software forwards credit card payment information to the accounting system.

16. The accounting system sends a confirmation to the order processing software.

17. The order processing software marks the order confirmed in the database.

18. The order processing software displays an order ID to the customer, and the use case ends.

Alternative: The Customer does not have a customer id
======================================================

1. The customer selects create account.

2. The system displays an account creation form.

3. The customer completes the name and shipping address fields.

4. If the customer is a corporate customer, include the alternative “Add Corporate Payment Information”, which is shown below.

5. Otherwise, the customer enters his or her credit card information into the payment fields, and a billing address (if different from the shipping address), into the billing address field.

6. The alternative ends.

Alternative: Add Corporate Payment Information
===============================================

1. The customer selects enter corporate payment information.

2. The system displays a corporate payment information form.

3. The customer selects the pay period, one of Net in 15 days, Net in 30 days, or Net in 45 days.

4. The customer enters the accounts receivable address.

5. The customer enters a contact person for the account.

6. The customer enters the PO number for the invoice.

7. The customer uses the note field to enter any additional information that may be required on the invoice.

8. The alternative ends.

If my customer has trouble understanding this use case, I would rewrite it to incorporate the steps of “Add Corporate Payment Information” into the alternative “The Customer does not have a customer id” in this manner:

Alternative: The Customer does not have a customer id
======================================================

1. The customer selects create account.

2. The system displays an account creation form.

3. The customer completes the name and shipping address fields.

4. If the customer is a corporate customer, do these steps:

4.1. The customer selects enter corporate payment information.

4.2. The system displays a corporate payment information form.

4.3. The customer selects the pay period, one of Net in 15 days, Net in 30 days, or Net in 45 days.

4.4. The customer enters the accounts receivable address.

4.5. The customer enters a contact person for the account.

4.6. The customer enters the PO number for the invoice.

4.7. The customer uses the note field to enter any additional information that may be required on the invoice.

5. Otherwise, the customer enters his or her credit card information into the payment fields, and a billing address (if different from the shipping address), into the billing address field.

6. The alternative ends.

 

Do you have a situation where you need to describe alternatives of alternatives? What approach do you use to structure your use cases in that situation?

Use Cases and Reports

Author: Geri Schneider Winters

I get my best ideas for these tips from you, my readers. This tip is a response to a question from Pete McNally on how to document requirements for reports and whether or not those requirements should be use cases.

Use cases are really meant for describing a process or task. If you are going to use a use case to describe a report, what you really want to describe is what job or task a person is doing when he or she creates and views a report. Why is the person reading the report? What will the person do with the information?

For example, assume someone wants to look at an application for insurance. The person wants to create and view a report of all the applications waiting for approval. Why? Because the person is reviewing applications to decide if they should be approved or not. So creating and viewing the report is one part of a larger use case – Determine Insurance Eligibility. A step of that use case would be to get a report of all applications waiting for approval. Another step would be to select an application for review (with any rules you have for which one to select, such as pick the application with the oldest filing date).

Here is a bit of an example to illustrate this concept:

Determine Insurance Eligibility
================================

1. The use case begins when the Evaluator asks the system for a list of all insurance applications waiting for approval.

2. The Evaluator selects the application that has the oldest filing date.

3. The system displays the details of that application.

4. The Evaluator enters the applicant’s age and medical information into the Health Calculator.

5. The Health Calculator determines the health index for the applicant and displays the health index to the Evaluator.

6. The Evaluator enters the applicant’s age, city and state of residence, number and age of dependents, and the health index into the Rate Calculator.

7. The Rate Calculator calculates the rate to be charged for the insurance.

…. There would probably be other steps here.

Alternatives
============
Application is denied

Now, what about step 1? What does that list of applications (report) look like? For that, you would use a report specification.

A report specification is a document that describes a report. In this document, you will describe the information that the user will enter into the system, how the report information is obtained or calculated, and what information is displayed to the user. You might also include a page with the design of the report, showing the various fields and the layout of the report. You can include any rules or algorithms that are used to create the report. You can include restrictions on who is allowed to generate or view the report, or indications as to when the report is run (for example, whenever needed, every night, once a week, once a month, once a quarter).

If there is no process that you can describe that includes creating a report, or viewing a report, then you do not need a use case at all. Just use the report specification to describe the contents of the report. It does not make sense to me to write a use case like this:

Create Quarterly Sales Report
=============================

1. The use case begins when the Accountant selects Generate Quarterly Sales Report.

2. The system calculates and displays the report.

3. The Accountant selects Save Report.

4. The system saves the report.

This use case provides me almost no useful information, and the little information it does provide can be put into the report specification with the other information about the report. There is no point to this use case, so why bother writing it?

Alerts and notifications may similarly fit better into another format.

Remember that not all requirements are use cases. Use Cases are great at describing tasks or processes – but not everything is a task or process. Reports are better described with a report specification document.

 

How do you describe reports, alerts, and notifications? Do you have a template for those types of requirements?

Do you see the usefulness of describing a task or process that includes creating and viewing a report?

 

Alternative Flows of Events

Author: Geri Schneider Winters

When you find an alternative to a use case basic flow, you have two different ways to handle it. One way is to put the alternative in the steps of the basic flow. That way of handling alternatives was described in a previous tip.

Another way to handle alternatives is to make a new section of your use case document for alternative flows. This section generally comes after the basic flow in your document. You write the basic flow to show the most common way of doing the use case, and the alternative flows list the other ways of doing the same use case.

I start by making a list of alternatives, using names and possibly brief descriptions. Let us assume we are working on a use case for a customer to Place an Order. While writing the basic flow, we assume that the most common form of payment will be credit card, so we write the basic flow showing that the customer is paying by credit card. I list the alternate forms of payment in the Alternative Flows section. Here is the example:

Place Order Use Case
Basic Flow of Events
====================

1. The use case begins when the customer selects Place Order in the order processing software.

2. The order processing software displays an order form to the customer.

3. The customer enters his or her name and address into the order form.

4. As long as the customer enters products, repeat these steps:

5. The customer enters a product code into the order form.

6. The order form displays a description and price for the product to the customer.

7. The order form adds the price to the order total.

end the repeat loop

8. The customer selects the credit card payment type on the order form.

9. The order form displays fields for the cardholder name, card number, expiration date, and verification code.

10. The customer enters credit card payment information into the order form.

11. The customer selects the Submit button on the order form.

12. The order form sends the information entered by the customer to the order processing software.

13. The order processing software verifies the information from the order form.

14. The order processing software saves the order as pending in the database.

15. The order processing software forwards credit card payment information to the accounting system.

16. The accounting system sends a confirmation to the order processing software.

17. The order processing software marks the order confirmed in the database.

18. The order processing software displays an order ID to the customer, and the use case ends.

Alternative Flows of Events
===========================
Customer Pays by Check or money order
Customer Pays by PayPal
Customer Pays by Cash
Customer Pays by some other method

Now at some point in time, I will need to add detail to the alternatives to describe how each alternative will work in my system. One way to do this is to copy the basic flow of events and change the steps that are different. I prefer the second approach, which is to just list the changed steps.

Below are the detailed alternatives for the use case. I am showing a couple of different approaches to writing the alternatives in the following examples.

Alternative 1: Customer Pays by Check
or money order
=====================================
In the Basic Flow of Events, replace steps 8-10 with the following:

1. The customer selects the check or money order payment type on the order form.

Alternative 2: Customer Pays by PayPal
======================================
Do the Basic Flow of Events, steps 1-7.

8. The customer selects the PayPal payment type on the order form.

9. The order form sends the order total and the company PayPal account name to the PayPal site.

10. The PayPal site displays a payment form to the customer.

11. The customer enters his or her PayPal payment information into the PayPal site.

12. The PayPal site sends the payment information to the order form.

The basic flow resumes at step 11.

Customer Pays by Cash
=====================
This is an error. We do not accept payment by cash.

Customer Pays by some other method
==================================
This is an error. We only accept payment by credit card, check, money order, or Paypal.

My basic rule for handling alternatives is this: If the alternative is short, just 1 or 2 steps, then put the alternative inline to the Basic Flow of Events as described in a previous tip. If the alternative is longer, then make a separate alternative flow of events.

How do you handle alternatives to the Basic Flow of Events?

Add alternatives to your existing use cases. If your company does not have a standard, try different approaches to see what works best for you.