How to Write Implementable, Testable, Accurate Use Cases

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.

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

We can rename the Approve Time-sheets and Disapprove Time-sheets by creating a Sign-Off on Employee Time-sheet use case. We can handle the approve and disapprove scenarios through the normal and alternate flows. Since we must define separate requirements to automate approving a time-sheet "Automatically Approve a Time-Sheet" can be a child or an "extends" use case of the "Sign-Off on Employee Time-Sheet". We were also informed of the condition that must be present for automation to occur. An employee's work hours must be equal to or less than 40 hours for a single work week.(In the real world this last statement would be a functional requirement.)

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.

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:

• Employee’s first and last name and Windows Log-In ID
• Project Name 
• Project Tasks 
• Hours Worked 
• Project Manager Name

We know Hours Worked can be any value from 0 to 24 for each day. We don’t know what value the user will enter so we can’t recommend reuse for this field. We're fairly sure the company doesn't want employees to manually enter their own name, the project name, the project tasks or project manager name for two reasons: 1. To generate reports data must be consistent. If users type in a value such as project name or project tasks some people will abbreviate the values, some will miss-spell one or more words and some will get it right. Therefore if a user wants to see all reports for a specific project, it would not be possible. This is because some users would have spelled the project name incorrectly. Others may even abbreviate the project name. 2. It's more time-consuming to have each employee enter the same values into a textbox. Alternatively, the system can be built so the values are entered once. User can then select the desired options from a  list of options.

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

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.

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.

6 Common Blunders That Cause An IT Project To Fail

Working in the Information Technology field for over 17 years has its advantages. Mostly, the knowledge I've gain from being hired to help an IT project recuperate from failure.  As America struggles to get back on its feet, most companies are working hard not to have a failed project. This is because failed IT projects are very costly in that the company spends money; but gets nothing in return. The following paragraphs list the top six reasons I've seen IT projects fail.

#1. Unfounded Requirements Assumptions

Within IT, we all know requirements are defined by the customer (see my blog article titled: Requirements: Understanding the Customer's Vision ). Requirements may come from taking notes during a meeting with the stakeholder and translating the notes into requirements. Alternatively, requirements may also come from making a list of questions that you ask the stakeholder. You then use the stakeholders' response(s) to define one or more requirements. So, what about assumptions? Even if a Business Analyst or Systems Analyst derives assumptions; the assumptions should also be discussed with the stakeholders. What's not a good practice is adding assumptions to a requirements document; and, distributing the document without discussing the assumptions with the stakeholders. Discussing assumptions with the appropriate stakeholder(s) before adding them to the requirements document is essential. This approach develops trust and shows the stakeholders they are in charge.

To avoid confusion or miscommunication, it's best to make sure all requirements are discussed, especially those derived from assumptions, before they are added to the requirements document.

#2. Making Promises Without Understanding What it Would Take to Keep Those Promises

This is one of the most frustrating problems--especially for those who diligently work hard to ensure all projects they support are successful. Those responsible for negotiating timelines with the customer should always talk to the team about proposed timelines before any promises are made. If short timelines are needed, the best approach is to prioritize requirements. This way requirements can be implemented by priority (understanding that all requirements can't be assigned a "High" priority). Negotiating realistic time-frames is key to successfully completing a project. On the other hand, making promises that include short turnaround times for larges amounts of work isn't a good idea. This usually leads to poor quality work that frustrates the customer and makes the entire IT team look and feel bad.

#3. Using a Role Other Than A Business Analyst/Systems Analyst to Gather Requirements
Requirements gathering is about more than just talking and writing. The Business Analyst/Systems Analyst responsible for defining requirements has learned elicitation techniques to define what the customer needs and wants. In addition, the Analyst has learned Gap Analysis techniques, traceability and other requirements-related techniques. Assuming anyone on the team, including Technical Writers or Developers, can define requirements can lead to costly mistakes. The roles in IT are divided such that each team member brings the specialty needed to accurately accomplish specific activities within the Software Development Life Cycle. When a practice other than an industry best practice is used; unwanted, unexpected results will usually surface.

#4. Releasing Software Without Proper Documentation

Before a new system is released, the proper documentation should be created. Most team members hate writing documentation; but that doesn't minimize the fact that system documentation is crucial. Any new business application should be accompanied by the following:

a. End-User materials - User's guides, getting started guides, quick reference guides and other materials needed to tell the user how to install, setup and use the system is important. (See my blog article titled Technical Writing & Technical Training Materials.)

b. Training Materials - Some systems may be complex enough to require user training. For example, Enterprise Resource Planning Systems (ERPs) should never be implemented without a cohesive plan to provide users with training. Training is important because it ensures users understand how to use the system to do their job. (See my blog article titled Technical Writing & Technical Training Materials.)

3. Re-engineered Business Process Document - If a new business application causes an organization's business process to change; it is imperative to educate the users. For example, to order a magazine users may call the support desk. The Customer Service Rep. do the following:

1. Take the order;
2. Type up a label and invoice; and
3. Send the request to the mailroom to fill the order and mail it out.

But, what if the company installs a new system. With the new system, the customer still calls the support desk. However, instead of typing up the invoice and mailing label; the Customer Service Rep. is now expected to enter the information into the system. The system then creates the invoice and sends a notification to the mailroom. Notice how end-user documentation will tell the Customer Service Rep. how to use the system to place the order. But, also notice how the process has drastically changed. Neither end-user nor training materials typically address the business process changes. This is why a plan should be implemented to document the business process change. The documented process change can be made part of the end-user's training. Or, the relevant documents can be given to employees impacted by the change. This ensures the organization continues to run smoothly with little downtime. It also ensures employees understand how to do their jobs with a new system in place. (See my blog article on Business Process Re-Engineering and Enterprise Architecture, Segment Architecture & Solution Architecture ,)

#5. Hiring a Project Manager Who Doesn't Understand the Project Manager's Role

 The Project Manager (PM) is one of the key people on the project. In addition to managing the project budget, timelines and deliverables; the PM is the key interface between the IT team and the customer. It is important that the PM understand the balance between customer responsibilities and the IT team.

I worked on an important project with a PM who negotiated due dates without establishing "how" the work was to get done. The PM wanted the customer to pick the templates and methodology that would be used to complete the work. With due dates already negotiated, I knew the more time it took to get the project started; the less time we had to complete the work. I knew the longer we "sat back and waited on the customer"; the less likely we were to succeed. Instead of sitting around I put together the templates based on the methodology I thought would be best for the customer's environment. Although I was not the PM; I still did not want to be part of a failed project. I pleaded with the PM to take the templates to the customer and ask the customer to simply review and provide input on what we provided. One meeting between the PM and customer gave us the go-ahead we needed to get started. The customer became enthusiastic because the project began to move forward. Things were getting done and the customer knew exactly what we would deliver and the approach we would use to do the work. As problems arose the PM was stumped. But, each time I used my experience to advise the PM on the best way to tackle the problem to achieve maximum project success.

Not everyone on a project team will have the experience I have. But if the team has a Project Manager who understands the various IT roles, SDLC methodologies, the customer's role and most importantly the Project Manager's role and responsibilities--things should go just fine.

#6. Not Using a Cohesive Methodology to Implement Software

It is not uncommon for a non-IT company to believe IT work can be accomplished without a methodology. The one company I stepped into that did not use an IT methodology to complete IT work experienced failure over and over again prior. The non-IT company hired IT people. But, since the non-IT people didn't know what they were doing; they inadvertedly hired IT people who didn't know what they were doing. So, the non-IT company ended up with an IT Department that had extremely weak IT skills.

Consequently, no one in the company trusted the IT Department. When I interviewed to join the IT team; the IT team assured me everyone (besides the IT Department) was responsible for the project failures. I wanted to discuss the methodology being used to do the work. I was told a methodology had not been adopted. So, the first thing I did was point out that it is impossible to successfully complete a project without using an "established" methodology.

I recommended an approach and created and circulated the templates. I documented the approach using a Visio diagram that everyone could follow and understand. Then I suggested that we try the approach out on a small scope of work, which we did. Everything went smoothly and the project was a success. The company adopted the methodology and greed no IT work would be done without using the agreed upon approach.

In short, never try to complete IT work without using an established methodology. These methodology were established after teams attempted to do work without them.

In Summary

Following is a list of things you can do to keep your IT project on the right track and avoid the blunders that cause projects to fail:

#1. Always have unfounded requirements assumptions approved by the stakeholder before they are stated as requirements.

#2. In IT, always understand what it will take to keep a promise before you make the promise.

#3. Always use a Business Analyst/Systems Analyst to gather and manage requirements.

#4. Always make sure proper documentation has been developed before releasing a new software application.

#5. Always hire a Project Manager who understands the Project Management role in its entirety and has experience successfully filling the role.

#6. Always use a cohesive methodology to implement a software application.