7 Mistakes Even the Best Make When Writing Use Cases
Do you find your developers have one follow-up question after another about how the system is really supposed to work, even though you documented the functionality in a use case? Worse yet, did your development team implement something completely different than you and your business stakeholders expected? Or, do your testers (bless their souls) come back to you with question upon question about what to test?
Use cases are a valuable requirements tool for capturing functional requirements in the context of user actions. Along with their super-powerful side-kick, wireframes, they can be a tool to finally get everyone on the same page about software requirements.
But some very common use case mistakes make use cases difficult to understand, and can actually create more ambiguity about the requirements.
You can avoid a lot of pain and suffering for everyone on your team by being sure you don’t make some of the most common use case mistakes that lead to ambiguity.
(These are real mistakes that I see again and again in the first drafts of our Use Case and Wireframes participants, but not in their second!)
Use Case Writing Mistake #1 – Include User Interface Details
By far the most common mistake we see in use cases is that they use the language of the user interface to talk about the user behavior. For example, instead of “Actor X creates a new account” they read as “Actor X clicks the new account button (or tab, or whatever).”
Using user interface details leads to ambiguity. This is counter-intuitive because “clicks the new account button” seems much more specific than “creates an account.” However, sometimes the name of the user interface element doesn’t clearly identify the action the user is taking and so it creates ambiguity about the actual step that we need from the user for the system to be successful. (Moreover, if you happen to change the name of the button or the tab, you could have a lot of use case updates to make. Talk about a maintenance nightmare!)
But, we’ve gone on for awhile about this mistake. Let’s get to the others, because there are plenty!
Use Case Writing Mistake #2 – Not Specify a System Response to a User Action
The next most common mistake we see, especially from individuals without a lot of exposure to information technology projects, is that the use cases are very process-oriented. The use case is crystal clear about all the steps the user needs to take, but it is missing the corresponding system action that needs to happen in response to each user step.
In a use case, just about every user step should have a corresponding user response or action. If it doesn’t, your development team isn’t clear on what the system is supposed to do to hold up its part of the bargain. This leads to assumptions being made or questions being asked during implementation.
Use Case Writing Mistake #3 – Include Technical Details
Another common mistake, and this one tends to come from more technically-focused professionals, is that the use case includes technical details that are not required to understand how the user interacts with the system.
Common examples of technical details include:
- Specific data elements or data tables.
- Names of system components that wouldn’t be visible to an ordinary end user of the system.
- System-triggered processes or procedures that need to run.
Including too many technical details can clarify things for the technical team, but breaks the flow of the use case and makes it difficult for your business stakeholders to understand and your testers to test. These details are best saved for a technical design document.
Use Case Writing Mistake #4 – Inconsistent with Wireframes
While use cases can stand alone as a requirements document, often they are created along with wireframes that show either the flow or one possible flow through a set of screens to realize the use case.
It’s very common for the use cases and the wireframes to get out of sync. For example, there could be a sequence of steps that’s not represented in the wireframe or the wireframe could lack the buttons and triggers necessary to fully realize the functionality in the use case.
Inconsistency in final deliverables creates confusion because it’s not clear which deliverable should be the true source of requirements. (And when there is lack of clarity, developers tend to choose visuals because they are easier to consume.)
Use Case Writing Mistake #5 – Unclear Where Alternates and Exceptions Branch Off the Main Flow
One of the useful elements of use cases is that they enable you to focus on the basic flow or “happy path” independent of all the variations that can occur along that path. These variations are called alternate and exception flows.
When detailing an alternate or exception flow, it’s preferable to identify a specific step in the basic flow where the alternate or exception begins or is triggered. Similarly, when the description of the flow is complete, you should indicate the step in the basic flow where the flow picks back up.
This habit makes less likely that you’ll miss steps in your basic flow. (Often when I notice these mistakes, there is no appropriate step in the basic flow to branch off from, which often means a system check is missing.) It also clarifies for your reader exactly when and how the alternates and exceptions get triggered.
Use Case Writing Mistake #6 – Include Out of Scope Steps
A use case should be fairly discrete. It should describe the sequence of steps (and all necessary variations) for accomplishing one specific user goal, such as creating an account or sending an email or generating a report.
A common mistake is to include steps that happen before the pre-conditions, after the post-conditions, or are otherwise unrelated to the user’s goal in the use case. This mistake is an indicator that the use case needs to be split into more than one use case.
This mistake leads to missing requirements because the more you try to cover in a single use case, the more likely you are to overlook steps and alternate paths through it.
Use Case Writing Mistake #7 – Inconsistent Terminology
A final mistake that can cause significant confusion is when BAs use terms inconsistently. For example, it’s common for a use case to describe a flow of steps to process a specific type of information.
Let’s just say in this scenario, we’re talking about creating a new article to publish on this website. If step 1 refers to an article as a “blog post,” step 3 as an “article,” and in step 5 there’s a reference to a “published content item,” it’s unclear as to whether these are all the same concepts or different concepts.
Not knowing the business jargon, your technical stakeholders will most likely assume that there are three different concepts that need to be implemented with different data elements and then have questions about how one ties to another.
How to Avoid These Mistakes When Writing Use Cases
If you are making any of these use case writing mistakes, you could be losing the opportunity to create clear and concise functional requirements that are easy for your stakeholders to understand, provide feedback on, and implement.
Review your latest use case for each of the mistakes mentioned and work to correct it. Better yet, trade use cases with a peer and review each other’s work for evidence of these 7 mistakes. Often an outside observer can see what we don’t.
Get Feedback on Your Use Case Cases (and Wireframes Too)
Join us for Use Cases and Wireframes – a virtual course where I walk you through my process for creating a use case with associated wireframes and how to ensure a use case is clear and complete. The professional credit option also includes a bit of feedback on your use case and 8 PDs or CDUs (upon successful course completion).
Source: Bridging the Gap BA