Thursday 12 August 2010

Thoughts about Writing Use Cases and User Stories

Every now and then people ask me about how to write use cases, preferrably ones that are usefull. I admit this is giving me fixed feelings: I'm happy to help and I'm pleased that people still find value in these, but at the same time I find myself feeling annoyed and disappointed about how rarely projects utilise Use Cases these days.

Before agile processes became the hype they are today Use Cases were the bread and butter of any new development project that (when done properly) allowed architects to think things through few times while writing them, explained to the developers what was needed and how things should happen as well as gave the testers a solid base to begin writing their Test Cases. After all, from a good Use Case several Test Cases could be derived starting from the Happy Day -test scenario.

But I digress.

A Use Case describes a single operation performed by the end-user, such as New User Registration, User Login or Search by Using Key Word(s) without addressing techical implementation details in any way. In other words, a Use Cases explain who uses the system in question, what they can do with it under which circumstances.

When writing Use Cases one should usually imagine another user operating the system through specific user interface. There are several questions that need answering: what is the user trying to accomplish? What information the system needs in order to help the user? What individual steps user needs to perform in order to reach the goal? Does the Use Case include interaction between the user and the system? How to keep things simple and intuitive?

Basic Use Case Structure
When I'm writing Use Cases I typically utilise following basic structure. While various books and processes introduce Use Cases with quite a few more fields than what I have listed below, my experience has shown that these are the ones most commonly needed.

UC FIELD DESCRIPTION
ID A unique identifier for the given Use Case.

[group id] - [use case number]
For example, ProjectAwesome-42 or UC-001.

A good notation provides identifiers that are unique, clear and informative within the given project context.

Note: A common mistake is to refer to a use case by its title, document chapter or even document page number. All these are likely to change during writing and editing which would then propagate to all those other documents that reference the Use Case.
Name / Title The name of the Use Case.

For example, Create User, or Request New Password.

Note: A good name typically follows verb-noun format (do someting). Keep it simple, keep it clear.
Summary Short verbal description explaining what this Use Case is about. Few sentences are usually enough.

For example, The user creates a new user account by submitting the registration form containing required and possibly additional optional personal information.
Priority Describes how important this Use Case is considering the overall usability of the system. During the early stages of the planning a priority hierarchy of three levels is usually enough:
  • (1) Essential: The system will not be production ready before this UC has been implemented. A core Use Case.
  • (3) Normal: This UC is needed and once implemented will greatly improve the overall usability of the system, but it can wait until the essential Use Cases have been implemented first (it is likely that this UC cannot be implemented before some essential UC).
  • (5) Nice-to-Have: While this UC could be beneficial for the end-users and improve the overall system, it is not strictly speaking required. Can be implemented should there be time and resources.
At later stages the priority hierarchy can be expanded to include five levels especially if there are large number of Use Cases with the same priority (and there often is). It also helps to highlight which Use Cases enable the development of other Use Cases.
Actor(s) Actor is an end-user archetype, or a role that can utilise this specific Use Case.

For example, AnonymousCustomer, Admistrator, Secretary Or Client Service.

Each Use Case can have one, two or several actors.

It is also good to keep in mind that end-user roles can evolve over time: one and the same user could begin as an Anonymous user when she enters the Create User UC; after successful registration the end-user might become a common Secretary user until she is given the Administrator privileges after which she might retain both Secretary and Administrator roles.

Note: It would be a topic for another discussion to consider whether Administrator should automatically include Secretary privileges or should they be kept separate at all times. After all, is the Administrator suppose to also do what Secretary does or should the concerns be kept separate at role levels? My opinion usually is to separate the concerns and enable the assignment of multiple roles when needed.
Preconditions What must have happened before this Use Case can be accessed?

For example, User has logged in or Account has money.

Often a Use Case can be a precondition for another Use Case, such as the requirement that the user has logged in. When this is the case use Use Case ID and Name as precondition reference (e.g. UC-003 Login User).

Another common situation is where certain property value(s) act as precondition. For example, UC Withdraw Money cannot happen if the user's account has no money.
Steps What the Use Case is actually about is explained here step by step. For example,

Start: Actor enters Login screen.
Step 1: Actor provides username and password to appropriate form fields.
Final Step: Actor clicks Login button.

Post-conditions Post-conditions list key changes in the system after the Use Case has been completed.

For example, after successful login the post-condition could be User has logged in and can access privileged services. Or if money has been withdrawn from a user account the post-condition could be the updated account balance and closed transaction.
Exceptions Where as Steps essentially explain the Happy Day -scenario (e.g. when everything goes as typically expected) there are usually various foreseen exceptions. Most common example is a failed field validation.

For example, Login might have following exceptions:

E-1: Incorrect username: The Actor is taken back to the login screen and an error message is shown: "Incorrect username and/or password".

E-2: Incorrect password: The Actor is taken back to the login screen and an error message is shown: "Incorrect username and/or password".

E-3: Account locked: The Actor is taken back to the login screen and an error message is shown: "Unable to login: user account has been locked. Please contact customer service for support."
Comments As Use Cases tend to go through multiple revisions it is often useful to have a place for comments and suggestions.

A bare-bones Use Case might do without pre- and post-conditions and priority, but eventually somebody has to figure these out before the Use Case can be implemented.

Use Case Iterations
Use Cases typically evolve through multiple iterations. Consider following:

First version: Once a need for a UC has been identified create the basic structure with just ID and Name.

Second version: Think about who needs this use case and what actually should happen on a high level. This defines Actor(s) and Summary.

Third version: Dive into details and think step-by-step what information the system needs and through which actions the end-user should provide that information. Each step might have 0..n (zero to many) exceptions so which ones can you identify at this point? More can be added in following iterations.

Fourth version: After most of the system's use cases has been identified are there some obvious Use Cases or property values that would act as preconditions to other Use Cases? Often one comes up with a precondition only to realise that it is actually a new Use Case.

Fifth version: Through discussions with various stakeholders and reviews Use Case begins to shape into its final form, but there are likely to be some more changes along the road...

Use Cases vs. User Stories
Use Cases are similar to User Stories often used in Agile processes such as Scrum. The main difference is that User Stories tend to be high level prose where as Use Cases are more structured and detailed.

Consider following example describing a user login.

USER STORY: Anonymous User Logs In
Description: The user opens the login page where he must provide valid USERNAME and PASSWORD combination. The basic form validation checks that the USERNAME exists, PASSWORD matches the one in the database and that the account is active. After successfull login user can access all functionalities according to his role privileges.

How to demo: First try to access some functionality that requires user to login. This should fail and user is automatically taken to login page. 

Next try login with incorrect username and/or password. The login page reloads and shows appropriate error message.

Finally login with valid credentials and after successful login attempt to access the same functionality as before login. This time functionality can be accessed.

USE CASE: Anonymous User Logs In
ID UC-02
Name / Title User Login
Summary User provides required login credentials in order to gain system access.
Priority Essential
Actor(s) Anonymous
Preconditions n/a
Steps Start: Actor enters Login screen.


Step 1: Actor provides username and password to appropriate form fields.


Final Step: Actor clicks Login button.
Post-conditions User has logged in and can access privileged services.
Exceptions E-1: Incorrect username: The Actor is taken back to the login screen and an error message is shown: "Incorrect username and/or password".

E-2: Incorrect password: The Actor is taken back to the login screen and an error message is shown: "Incorrect username and/or password".

E-3: Account locked: The Actor is taken back to the login screen and an error message is shown: "Unable to login: user account has been locked. Please contact customer service for support."
Comments n/a