In this article I discuss how to write use cases that accurately reflect what stakeholders want and ensure the use cases are implementable and testable.
First, let's define a use case. A use case is a group of words that depict system behaviors or actions. Put another way, a use case defines an action the user can perform using a system or software application. When stakeholders discuss the tasks they want users to complete using a software product, the information may or may not be stated in the form of a use case. But, there are several rules you can apply to define use cases, from stakeholder statements, more easily: 1. always start the use case with an action word; 2. each use case should always define a single action; and, 3. each use case should convey a task a user can use a computer to perform.
To accurately capture the actions stakeholders want users to perform you have to talk to stakeholders. It's a very good practice, whenever possible; to record the requirements gathering sessions so you can later verify what you "think" you heard in the meeting. Capturing the information directly from the source is a great start in your endeavor to ensure the requirements are accurate. Note that you will still need to validate the use cases by circulating them for review and approval.
Once you understand the actions the stakeholder wants to perform using the system, you can review the statements to create the use cases. Remember each use case must provide an action a user can perform when sitting in front of the computer. For example, "unable to enroll a student because of outstanding debt" is not a use case. A user cannot sit in front of a system and use it to "unable to enroll a student because of outstanding debit". The user can, however, sit in front of a computer and use it to "deny a student’s enrollment". Ensuring requirements are documented as an actionable statement is likely the reason user stories are gaining popularity. When you write user stories you begin with a phrase: As an "actor" I can "perform this task"... This approach forces everyone to think "what actions do I want to perform when using the software?"
In our previous example, we said a user can sit in front of a software application and use the software to "deny a student's enrollment request". Denying the student's enrollment "because of outstanding debit" can be one scenario in which the student's enrollment is denied. However, there could also be other reasons why the enrollment is denied. For example, a student's enrollment might be denied because "the student's SAT scores are too low". So you could have a use case: Deny Enrollment and use the Normal and Alternate flows to depict the scenarios.
Once you have defined the use cases that outline the actions users should be able to perform, there’s still more work to do. You will need to uncover additional use cases required to build a complete system. For example, let's say a stakeholder told you he wants a system that can "track employee hours for each project to accurately manage project costs". In this example we know exactly what the business objective is. Further elicitation sessions helped us identify specific actions users should be able to perform as follows:
We can carefully analyze the information and break the statements into single actions the user can perform:
Next we need to combine View Project Hours by Customer and View Project Hours by Project Task into one use case. Both use cases perform the exact same action "View Project Hours". The only difference between the use cases is the data (i.e., in one scenario (such as the normal flow) users view project hours by customer; however, in the other scenario (such as the alternate flow) users view project hours by project task).
We can name our last use case View Project Tasks. In our use case description we can point out that the project tasks should be viewable by employee.
Here we look at the "Sign-Off on Employee Time-Sheet" use case in greater detail. In this example we will design the use case so the normal flow is used to "mark time-sheet as approved". The alternate flow is used to "mark time-sheet as disapproved". We also need to capture more information from stakeholders so we can more clearly define all of the functionality to be provided by the software. For example, what data elements do stakeholders want the time-sheet to display? So far we've only discussed project tasks and project hours. But we also know each employee has to complete a time-sheet; and, there is likely additional data the timesheet must capture. Note that your requirements management tool can be used to manage questions to make sure we track what questions we've received answers to. The following picture shows the Gap Analysis folder that includes the QUES type used to manage questions.
When we sit with the stakeholder we have pencil and paper in hand. We need to find out what the stakeholder envisions the time-sheet to look like. In other words what data will the time-sheet capture? As we discuss the data elements that should be included we can draw the fields on the piece of paper. Again, we are capturing what the stakeholder wants during the discussion to make sure the information is accurate.
The stakeholder decides the time-sheet should have the employee’s name, the name of the project, the project tasks assigned to the employee and the number of hours spent on each task. This could present a problem. If we only use the employee’s name, what happens when two employees have the same name? We could use the employee’s first name, last name and user’s Windows Log-in ID. We also learn that the Project Manager assigned to the project will review and approve time-sheets. This tells us there must be a way to associate the project manager with the project. If we created a rough sketch during the meeting; we can show it to the stakeholder. The stakeholder may agree or even make changes. Either way this will give us the information we need to define the time-sheet. Below are the fields we captured for the time-sheet:
We can now create the additional use cases needed to support the "Sign-Off on Employee Time-sheet" use case:
We would also need to add a requirement to ensure the employee’s first, last name and Windows Log-In ID are automatically added to the timesheet when the user creates it.Definition of a Use Case
First, let's define a use case. A use case is a group of words that depict system behaviors or actions. Put another way, a use case defines an action the user can perform using a system or software application. When stakeholders discuss the tasks they want users to complete using a software product, the information may or may not be stated in the form of a use case. But, there are several rules you can apply to define use cases, from stakeholder statements, more easily: 1. always start the use case with an action word; 2. each use case should always define a single action; and, 3. each use case should convey a task a user can use a computer to perform.
Accurately Capturing Use Cases
To accurately capture the actions stakeholders want users to perform you have to talk to stakeholders. It's a very good practice, whenever possible; to record the requirements gathering sessions so you can later verify what you "think" you heard in the meeting. Capturing the information directly from the source is a great start in your endeavor to ensure the requirements are accurate. Note that you will still need to validate the use cases by circulating them for review and approval.
Once you understand the actions the stakeholder wants to perform using the system, you can review the statements to create the use cases. Remember each use case must provide an action a user can perform when sitting in front of the computer. For example, "unable to enroll a student because of outstanding debt" is not a use case. A user cannot sit in front of a system and use it to "unable to enroll a student because of outstanding debit". The user can, however, sit in front of a computer and use it to "deny a student’s enrollment". Ensuring requirements are documented as an actionable statement is likely the reason user stories are gaining popularity. When you write user stories you begin with a phrase: As an "actor" I can "perform this task"... This approach forces everyone to think "what actions do I want to perform when using the software?"
In our previous example, we said a user can sit in front of a software application and use the software to "deny a student's enrollment request". Denying the student's enrollment "because of outstanding debit" can be one scenario in which the student's enrollment is denied. However, there could also be other reasons why the enrollment is denied. For example, a student's enrollment might be denied because "the student's SAT scores are too low". So you could have a use case: Deny Enrollment and use the Normal and Alternate flows to depict the scenarios.
Once you have defined the use cases that outline the actions users should be able to perform, there’s still more work to do. You will need to uncover additional use cases required to build a complete system. For example, let's say a stakeholder told you he wants a system that can "track employee hours for each project to accurately manage project costs". In this example we know exactly what the business objective is. Further elicitation sessions helped us identify specific actions users should be able to perform as follows:
- Approve and Disapprove Time-sheets manually (as well as automatically approve time-sheets).
- View Project Hours by Customer
- View project tasks by employee; and, view the number of hours each employee spends on a project task.
- Generate Project Cost Reports based on employee project hours
We can carefully analyze the information and break the statements into single actions the user can perform:
- Approve time-sheets (manually and through automation)
- Disapprove time-sheets (manually only)
- View Project Hours by customer
- View Project Hours by Project Task
- View Project Tasks by Employee
- Generate a Project Cost Report (Based on the information provided we know we have to include the employee’s hourly cost multiplied by the hours worked. But, we don’t know what date range should be used for this report. In the real world we would have to ask more questions. For this article we are going to focus on the first five actions.)
Next we need to combine View Project Hours by Customer and View Project Hours by Project Task into one use case. Both use cases perform the exact same action "View Project Hours". The only difference between the use cases is the data (i.e., in one scenario (such as the normal flow) users view project hours by customer; however, in the other scenario (such as the alternate flow) users view project hours by project task).
We can name our last use case View Project Tasks. In our use case description we can point out that the project tasks should be viewable by employee.
Sign-Off on Employee Time-sheet
Here we look at the "Sign-Off on Employee Time-Sheet" use case in greater detail. In this example we will design the use case so the normal flow is used to "mark time-sheet as approved". The alternate flow is used to "mark time-sheet as disapproved". We also need to capture more information from stakeholders so we can more clearly define all of the functionality to be provided by the software. For example, what data elements do stakeholders want the time-sheet to display? So far we've only discussed project tasks and project hours. But we also know each employee has to complete a time-sheet; and, there is likely additional data the timesheet must capture. Note that your requirements management tool can be used to manage questions to make sure we track what questions we've received answers to. The following picture shows the Gap Analysis folder that includes the QUES type used to manage questions.
 |
| QUES Requirements Type Added to Requirements Management System to Manage Questions/Responses |
When we sit with the stakeholder we have pencil and paper in hand. We need to find out what the stakeholder envisions the time-sheet to look like. In other words what data will the time-sheet capture? As we discuss the data elements that should be included we can draw the fields on the piece of paper. Again, we are capturing what the stakeholder wants during the discussion to make sure the information is accurate.
- Employee’s first and last name and Windows Log-In ID
- Project Name
- Project Tasks
- Hours Worked
- Project Manager Name
We can now create the additional use cases needed to support the "Sign-Off on Employee Time-sheet" use case:
- Add a Project (This use case provides the functionality that lets Project Managers add project names. It is also conceivable that the ability to Search Projects or even Edit Projects may be necessary, depending on the Vision for the system. )
- View a List of Projects (Users must be able to view a list of projects to select the correct project.)
- Add Project Tasks (This use case lets the Project Manager add project tasks for each project.); and
- View a List of Project Tasks (Users must be able to view a list of project task to select the proper tasks.)
In Conclusion
To accurately capture requirements it is best to host a requirements gathering session. And, it takes close communication to ensure the requirements are accurate. Making assumptions in a vacuum and circulating those assumptions without getting feedback first may lead to mistrust—depending on how well the stakeholders know you. Always confirm assumptions before circulating the assumptions. Clear communication is a great way to build trust and get the requirements right.
Lastly, as you name use cases give careful thought to the use case name. The name should identify a single action the user can perform while using the system. This approach ensures developers can implement the use cases and testers can test them with a specific objective in mind. And, in the end everyone knows exactly what to expect because the use cases are not ambiguous.
