Should you use use cases or process flow diagrams to document business requirements? At some level, they both document the same thing, they just document it differently. The best requirements will come from doing both – but what if you are forced to choose one? What are the tradeoffs between use cases and process flows? In this article we look at the documentation of failure handling.
Documenting Failure Modes or Error Handling
Failure handling is something that software has to do. In every process or use case, there are going to be non-trivial failures or other unanticipated events. The exercise of identifying those failure modes is relatively straightforward. Deciding what to do in each situation is harder. Documenting and communicating those requirements can be harder still.
A Simple Use Case Example of Failure
Alistair Cockburn uses a simple example in Writing Effective Use Cases, to describe how to handle this situation with a use case extension. We’re paraphrasing his example here:
1. User requests to update her billing information.
2. System requests authentication of user identity.
3. User enters authentication information.
4. System authenticates user.
5. System presents billing information for editing.
6. User edits her billing information.
7. User indicates that edits are complete.
8. System updates billing information.
9. System acknowledges update of billing information.
What happens if the user authentication fails?
Cockburn suggests using a use case extension to deal with this situation. His suggestion applied to our example would read:
4a. Failed authentication
4a1. System notifies user of failed authentication and re-requests authentication.
4a2. User re-enters authentication information.
4a3. System authenticates user.
One thing you will notice is that this is a linear representation of the use case. It includes the anticipated failure condition – failed authentication.
Process Flow Example of Failure
You can create the equivalent example of the Edit Billing Information use case as a process flow.
The process flow diagram provides two immediate benefits relative to the sample use case. First, by using swim-lanes, there is a visual reinforcement of the roles of the user and the system. The use case identifies the actor for each step as well – as text. Second, the decision box highlights the possibility of failure, and makes it obvious that there is a desired way to address failed user authentication. The use case shows this information, but only at the end of the prose, because of the linear structure of the text.
These benefits come from the spatial representation of the process. By laying out a diagram in two dimensions, you increase the information density of the artifact. The need for, and execution of authentication failure handling is more clear in this example.
More Complex Examples
Reviewing this simple example could lead you to conclude that there is near parity between the two documentation approaches. Consider a process with more failure modes, or even failures within failures. What if the system is required to lock out the user account after three failed authentication attempts? This is a straightforward extension to either example – but the use case form begins to get “clunky” with nesting extensions. The process flow diagram scales better to complexity.
Generalized Conditional Branching
This example can be generalized for any if…then situation.
When writing a use case, there is the often overlooked step of replacing “if…then” with “if…then…else.” It can be easy to overlook a missing branch to a decision tree. One of the goals of writing requirements is to write complete requirements. You want to avoid anything that makes it easy to write an incomplete requirement.
As a justification for making sure that you identify failure conditions and failure handling when writing use cases, Cockburn points out the completeness benefits. He says that you may even identify new actors, processes, and business rules while defining the failure handling extension of a use case step. We feel this is a weakness of the use case format, not a benefit of failure handling.
Other Factors
As with almost every element of requirements management, there are many factors to consider. Process flows are not universally better than use cases, or vice versa. This article focuses only on the need to deal with conditional branching.
For communicating the requirements associated with conditional branching in a process, a process flow diagram is better than a use case.
Latest Articles
Comments on all Articles
