I was just updating my Example UML Use Case diagram article and it occurred to me that if you're a Business Analyst, there are a couple of questions you can ask yourself as you write a Use Case (or User Story) that will help improve the quality of your writing. Two questions specifically come to mind:
Th first question came to mind as I added a "user story" to my Example Use Case Diagram article, and I kept wondering if I had everything covered in the user story. So I paused and asked myself, "What are the major points I need to cover here? What am I asking the reviewers of this use case to agree to?" The second question came to mind when I remembered an older blog post, UML Use Case best practice: Test your Use Cases with real data.
As I thought about my "User Logs In" use case, I paused to make a list of the items I was asking the reviewers of my document to agree to, and I came up with these main points:
Once I had these main points in mind I wrote my User Story. (I was going to write a Use Case here, but decided to write a User Story instead. I'll write a Use Case version of this same content in a future article.)
A "User Logs In" user story might look something like this:
A Website Visitor navigates to our user SSL-encrypted login page, and logs into the system using his username and password. Assuming his credentials are authenticated against our "users" data store and he has the role of Author, he's logged into the system and taken to his home page.
Alternatively, though not common, if a Website Visitor attempts to access an Add, Edit, or Delete URL, the user will be redirected to the login page. Assuming they log in successfully, in this case they will be redirected to the Add, Edit, or Delete URL they were attempting to access.
If a Website Visitor is unsuccessful in their login attempt, they will come right back to the login page, and an error message will show they were unsuccessful. There is no limit to the number of times a user may attempt to log in, the system will not throttle their login attempts in any way, and we will not log their failed login attempts (TBD).
Note that a user logs in they may have multiple roles in the system (Author, Editor, Publisher, etc.), and if so, they will inherit all of the permissions associated with all of these roles.
It's important to note a few specific things I'm doing here:
Other than the vagueness about the "user data store", I've actually written text like this before, so I think it's a reasonable User Story.
After writing a User Story or Use Case, the next thing I do is review it to make sure that everything I've written can be tested after the system is in place. Here are a few testable phrases from this text:
Hopefully many other tests can be inferred from my writing as well.
I think it's important to note that I also intentionally left a few things out that I initially had in the story. One important point I removed was this one:
Can you see why I removed this statement? It may be difficult to see this without thinking about the entire system, but I removed this statement because this point should have been covered in another Use Case titled something like "User Account is Created", and therefore, including the same statement here would be redundant. While this may seem like a small matter, this can be very confusing to reviewers, who will typically ask "Didn't we cover that point in the other Use Case? Why is it brought up here again?". During a recent large project I ran into this problem with reviewers several times, after which I became very specific about what I left out of a use case, as well as what I put into one.
As an interesting test, I also just realized that I left out a statement like this:
Do you think this User Story would be improved by adding this statement?
Note that the same content can be written in different ways, depending on the preferences of your organization:
Which writing style you choose is up to you and your organization. I personally prefer either the User Story or Use Case approaches, and I will add other requirements to my documents as needed. For instance, it's easier to write Performance Requirements as line items than to try to fit them into stories or use cases, so I write those in a separate "Performance Requirements" section of my documents.
Getting back to the questions I shared at the beginning of this article, I hope you can see where my initial questions helped me formulate this user story:
In summary, I hope this article about UML Use Case quality has been helpful. I believe asking yourself these questions will help improve the quality of your Use Cases.