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.
Ive found that sometimes a Use Case can be quite handy for showing the application of multiple conditions caused by business rules. Process maps can become very cluttered f you are applying multiple rules in one scenario, for example more than four or five conditions with two or even one swimlane can result in a quite complex diagram especially if the rules relate to each other and the lines start to cross. In the case of trying to show many rules I would say a Use Case would be more practical as the text ultimatley will become clearer than a diagram with many lines and boxes.
Hey Ben, thanks for reading and commenting!
On an enterprise-software-deployment project for a client, I found that we needed to do both. We were looking at ~50 cross-functional processes, with a couple hundred use cases.
For the different consumers of the requirements, the different documentation approaches each had their strengths. I’m hoping to tease apart specific scenarios, so that people can make order of the chaos of comparison.
Personally, I’ve found that a complex process is best depicted in its entirety with a flow, and developing tests / validations of that process is best done from a use case. I believe it is too easy to get lost in a sea of exceptions (and exceptions to exceptions) when using only prose. And I agree that a complex diagram makes it especially hard to envision a single scenario (or multiple single scenarios).
Thanks again for joining in on the conversation – hope to hear more from you!
Ive found the use case approach quite useful at the outset of a project when not everything clear and it is a bit chaotic. The danger with process maps is that people draw diagrams which end up reflecting things at high level and low level on one map.
The discipline Ive applied is to create a use case style document in Word which breaks the goals of the system/user down into smaller components document these using text and use these as the intial draft for discussion. Once more detail is added I can then look at drawing process maps which usually become really obvious after you have documented itin text form first
Ive seen people attempt to jump straight into documenting process maps first without thinking through what they are documenting and they tend to end up with very complicated maps which have high and low levels of detail and dont necessarily reflect the requirements or any detail particulary well.
Both tools are important and I agree with your points above. From this discussion I think which one to use first is also something worth considering. I like building up the text and requirements and then drawing the process maps rather than jumping straight into diagramtic process flows.
Hey Ben, thanks again for the great inputs!
The BA team I was leading on the project where we did both started with process flows. Right or wrong, it was in the overall charter for the project when we started. The BAs were all new, and definitely struggled with the variable level of detail you describe. With some coaching, we ended up with pretty consistent diagram levels.
As I think about it, I remember that the transition from business requirements analysis to application requirements and high level design was a little bumpy – BAs tended to get sucked into design activities, and struggled to reflect those implementation details in their process flows.
I think part of the challenge is that we documented processes “one level above procedures” – a low enough level of detail to capture the myriad of business rules for “special cases” and exceptions – these are processes that evolved over decades without revamping. It took effort to not move down the slippery slope.
In alignment with your comments – the way we documented process flows was to have a visio of the flow, with a companion word doc that included the prose. In that prose we captured context, explanations, and goals. We also “formally documented” the business requirements within the word docs.
As part of our communication and approval process, we explained to our stakeholders that the visio was a roadmap and reference, but the word doc represented the actual requirements.
I believe either approach (use case first or process first) will work, as long as you capture the contextual information – as you describe – in the first pass of whichever artifact you’re doing.
As an aside, I’ve seen people struggle with use case levels the same way you describe process map struggles. I don’t think either tool prevents the problem.
Thanks again for the great comments, glad to have you here at Tyner Blain!
I think we’ve ended up discussing one of the skills which makes a good Business Analyst! Deciding which tool to apply is just as important as how you use it. Getting the balance between high and low level detail is a fundamental concept of Business Analysis that many books on both process flows and use cases sometimes gloss over.
We actually use a software application called Provision (Im sure there are lots of other applications which perform in a similar way) which allows you to map the process flows just like you did in Visio but also allows you to attach the text you described in the Word document to each object in the process model. Its fundamentally a relational database which offers more interactivity and gets you over the problem of having to manage Visio charts and Word documents separately while also applying different levels to the models.
Process flows are dangerously straightforward but as you discovered can be hard to master. I agree the same applies to Use Cases although because they have an added level of “mystery” to those outside of the IT environment, i.e. any man and his dog can draw a picture whereas describing something in text requires more thought processes and slightly more discipline. That’s why I personally prefer Use Cases on the first pass for gathering initial requirements and use process flows later on BUT not in every case as I agree wholeheartedly with what you say.
It all depends on who your audience is, how much detail you need to capture and what you are showing to determine the best one to use, so I agree its not an either or scenario.
Fundamentally they are both useful ways of documenting requirements that need some practice to apply, just like any tool.
Thanks Ben, completely agree!
Is ProVision the product from Avoka? http://www.avoka.com/proforma/provision_overview.shtml
Looking forward to reading more of your thoughts here – I appreciate it very much.
That looks very very familiar, I suspect they maybe the Australian distributors for a version of the product, although dont quote me on that!
The actual web site for the main product is as follows, Ive copied the url for the software I use.
http://www.proformacorp.com/Products/enterprise.asp
Thanks Ben!
Definitely the same product – they have some of the same examples in a few of the screenshots, once you drill down.
Have y’all found that the benefits of using that tool (versus Visio) justify the cost for your team? If so – what are the characteristics of a team that you would assess to encourage/discourage the use?
The main benefits of using a tool such as this over Visio is that it effectively works like a database therefore you don’t have to recreate objects for each diagram you create. For example I can create a deliverable called “Customer Order” attach attributes to the background such as type, timings and re-use this throughout the whole model. I can also create workflows and re-use the deliverable object as a connector between activities on the workflow. I dont have to keep recreating things in order to document them. Another example would be a rules object which would define a business rule to be applied, I can use this object in a number of maps without worrying about it getting out of synch or lost in a Word document as its only created once. The tool does also allow you to attach documents to models so you could even manage Word documents from within the tool by attaching them in the background.
I think for us the real benefit to the team has been a structured way of capturing and documenting analysis. The software forces you to use a certain framework which is a good for teams who may not work in a standard way.
The standard “Enterprise†framework provided in the tool means information will be captured consistently. (it also caters for additional frameworks such as Sarbanes Oxley and Rummler Brache terminology). Using standard terms and centralising objects for re-use reduces the requirement to manage numerous Word/Excel/Visio diagrams from multiple users..
You do need to think a bit more about how you could document things when you dont have the uncontrolled(?) freedom of a Visio diagram and you have a more rigid framework for capturing information.
Ive been using the software for nearly two years and sometimes I only feel like Ive scratched the surface! It does provide flexibility within the standard framework to pretty much document anything and everything in a much more controlled way.
In terms of cost its more expensive than Visio but is more beneficial for teams who lack the discipline and rigour of a Word/Visio combo. In theory it offers a more controlled way of building models in a team environment which would be suited to both formal and more informal teams. You could achieve everything you wanted using Visio and Word with the tool but with these you would end up administering much more at the expense of documenting and analysing.
The funny thing is its actually very easy to create process models and you forget how much time you would have spent building them in Visio. You can knock a multilevel map up in 20 minutes which might take an hour in Visio so you get more done.
I suggest trying it out for a bit as they offer a demo of the application for 15 days on the site which you can download (and no Im not on commission!)
Thanks again, Ben! Awesome stuff. And even if you were on commission, I’d still let you link here – you’re providing a valuable commentary and reference.
Great dialog. I’ve used both the use case and the process diagram as you’ve suggested. One component I’ve found useful is initial data flow. This is captured as data inputs and outputs on the process diagram. This is sometimes referred to as an EFBD, enhanced flow block diagram. The EFBD goes a long way in defining new processes, when we ask ourselves is the process sufficient to produce what we want.
When do you folks consider data input in context of the process diagram?
The process used to be do the design, then add error processing. The error processing was added long after the requirements. They originate in the implementation. They are implementation constraints, so you have to deal with them in the design phase decisions. That does not mean that they would be passed through to the requirement phase decisions. No user says, “hey, I want to make a mistake today.” I can’t see a user buying an error processing application.
It might be that you are specifying the error processing, so that QA ensures that the branch testing gets done as part of the acceptance test, but they seem like unit tests.
I’d rather leave error processing and issues that are brought into the application from APIs to the programmers, particularly in Agile. Plenty of branches and UI controls originate from APIs. It seems to me that this makes the product manager too intimate with the code.
This issue is addressed in the book “Arquitetura Orientada a Serviços – Fundamentos e Estratégias”, by Jose Carlos Lazzeri. The author suggests apply process flow for requirements capturing in an interesting way.
Which is best and which to used first I think depends not only on the BA but also the SMEs and the stakeholders that need to sign off on the Use Cases / Storyboards / Process flows. One project I was involved with everything was based on written Use Cases and another was all about diagrams.
Think this discussion was very good.
Thanks, Jim, and welcome to Tyner Blain!
I completely agree about the focus on your audience. Every time I’ve used more than one format to describe different aspects of the same product / project, I find that we generate additional insights. So while I may start with one format, I usually end up including some other view too.