UML Use Case quality - Questions to ask yourself when writing a Use Case

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:

• What are the main points of this use case? (Which might also be phrased, "What points about this business process do I need to make sure everyone really agrees about?")
• Are the statements I've written testable?

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.

Major points of my "User Logs In" Use Case

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:

1. The username and password were assigned to the Author at some earlier time; this is a pre-condition of this story.
2. User and Role information is kept in some form of data store. (More on this below.)
3. An Author is a role in our system.
4. The Author role has permissions which can be configured by a "super user", and those permissions are not important to this story.
5. A user who logs in can have multiple roles (Author, Editor, Publisher, etc.).
6. There is a standard user login web page.
7. There are alternate ways to get redirected to the login page.
8. Login attempts are unlimited. We don't throttle them or limit them.
9. Until an Author logs in, they are really a "user" of the system, which I refer to as a Website Visitor.

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.)

The "User Logs In" user story

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:

1. I tried to capture all the bullet points shown above in the context of a "user story."
2. I am fairly vague about how the user is authenticated. With a real company I would mention the specific data store authentication will happen against, typically an LDAP system or database. I've seen large companies have multiple "user" databases, and this can be an important point of agreement. (There might also be some sort of single sign-on system here.)
3. I also don't mention any particulars of how the authentication happens. For some companies it might be important to mention that "Oh by the way, we're going to store their passwords unencrypted", that sort of thing.
4. Conversely, The "TBD" item is intentionally included to make sure the reviewers are awake and agree to this point.

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.

Are my statements testable?

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:

1. The login form must be SSL-enabled.
2. User credentials are authenticated against the "users" data store.
3. The Website Visitor is redirected to their home page after a "normal" login.
4. The Website Visitor is redirected to the Add, Edit, or Delete page after that type of login.

Hopefully many other tests can be inferred from my writing as well.

What I left out

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:

• The username and password supplied must meet the minimum length and character requirements we have agreed to.

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:

• The system only lets users log into our system using our data store; it specifically does not let users authenticate using Open ID, Facebook Connect, or other login systems.

Do you think this User Story would be improved by adding this statement?

User Stories, Use Cases, and Requirements

Note that the same content can be written in different ways, depending on the preferences of your organization:

1. The format shown here is what I call a User Story. The idea of a User Story was first written about in the eXtreme Programming books, and their User Story would probably be even shorter than what I've written here.
2. A Use Case version of this same information would be written in a more formal, step-by-step approach, and in this case we contain several alternate scenarios.
3. This same information could be written as a series of requirements. The bullet points I started with are vague requirements which could be converted into more formal requirements.

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.

Back to the questions

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:

1. I began with my question, "What are they key points about this business process that I need to make sure the reviewers really agree with?"
2. I created a list of all the key points I thought of, and then captured them in the context of a User Story.
3. In an area that I thought needed some discussion, I was extremely specific about what the system would not do, and also included the "TBD" text.
4. After writing this story, I went back and reviewed it with the question, "Is everything I've written testable?" If something was too vague to be testable, I would correct it before sharing it with anyone.

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.