Classic Use Case Mistakes

Over the years I have come to understand the role of use cases in the requirements definition activities. They are very valuable if done properly. The problem I continue to see in many organizations is that they are not done properly. So what are some of the mistakes that can help ensure you are getting the most value from your use cases? 

Mistake Number 1: Creating inside-out user cases. 

Results: Use cases that are written from the perspective of the system, not the user. These use cases are often complex and technical. The problem is that most of the time users don’t understand this because it is not natural to them. This makes it difficult to get valuable feedback from the users. 

Actions: Make sure the user’s perspective is maintained when writing use cases. 

Mistake Number 2: Including user interface details in use cases.

Results: Use cases that include a lot of steps that really don’t contribute to understanding how the user will interact with the system. You may see details about where error message are displayed, radio buttons, links, other details about a screen that add to the confusion. Often use case writers try to include every possible action as a part of the use case flow. For example, every possible selection has an alternate flow titled “User Selects Cancel Button”. Adding all of these alternate flows results in a use case that is much more complex that it needs to be. 

Actions: During requirements gathering keep the user interface details out. They are a distraction from defining the interactions that need to occur. Consider keeping user interface requirements in a separate section. This can be used as a checklist when testing to make sure the entire set of interface requirements are met for each screen. 

Mistake Number 3: Expanding the system boundary. It is difficult to keep in mind the scope of the system you’re developing. For example, consider other systems that interact with the system under development. Is it inside the boundary? Is it an actor? Should it not be shown on the use case diagrams? Results: When actors are included which are outside the control of the team, a lot of time is spent documenting a system that already exists and will not be changed. A lot of time will be spent explaining to users that the system just “works the way it does”. You are better off not including details about systems that are outside the boundary of the system. 

Actions: If the team is responsible for implementing and testing it, then it is inside the system boundary. If it is a separate system done by a separate team, it becomes an actor. 

Mistake Number 4: Creating use case interactions that don’t provide value to an actor. 

Results: Use cases that don’t provide any value to the actor. These use cases may not be derived from business requirements. Or they may be derived from business requirements but don’t contribute to the overall goal of the business requirement. 

Actions: Make sure every use case has a clearly stated goal that provides a benefit to an actor. Note that the actor that benefits does not have to be the primary actor in the use case. 

These are typical mistakes made when writing use cases. Many times the end result is a set of very long, very complex, and very technical use cases that provide very little benefit to end users or developers. Consider training your team on writing good use cases before just throwing them out the use case wolves. It will be worth the time and money spent to ensure use cases are providing the maximum benefit to your project.

(Reference: Use Cases: Requirements in Context by Kulak and Guiney)


 By Marcia Stinson 

Is your ship sinking?

Many years ago I worked on a huge project to upgrade a complex mission planning system to new hardware and a new language. Our requirements were simple (I can hear chuckling now). Simply make the new system work just the way the old system worked. Oh, and don’t forget to improve performance as much as possible. Oh, and don’t forget to improve the user interface to make it easier to use. And, oh yes, if you are working on a module that has a defect against it go ahead and correct that defect if it won’t take too much time. And, finally, oh yes, make sure the project is completed on time.

So the management team spent months preparing for this project. They looked at all of the software involved. They looked at resources. They got estimates for the time required to rewrite each piece of code. They assigned priorities to each task. They looked at resources and scheduled resources for each task. They created a project schedule. They created a huge spider chart that covered two walls showing the relationship and order of the tasks. That spider chart was so impressive when you came into the area and saw it. I’m sure you would think “Wow, they have this project under control and well managed.” The ship was ready to sail.

The project was supposed to be completed in a year. Would you surprised if I told you we didn’t complete it in a year. I forgot to mention that we had no requirements for the previous system. We were just working off of things by actually running the old system to see what it did. We had a couple of expert users who were checking things as we went to make sure it was acceptable. They were actually our testing team as it turned out. So at the end of the year we were 99% complete according the project schedule, spider chart, and all of the other metrics. The problem was that those metrics were all based off assigned values by the worker bees. Things were shown to be complete that weren’t actually 100% complete – they were close. Reviews were shown as complete whenever the meeting was held regardless of the follow up activities that were required. So everything looked great on paper. We all knew that wasn’t true. The ship had hit the iceberg.

Another year went by and we worked very hard. We were told to work harder and work smarter. But no overtime. Just get the job finished. We all worked hard. We ran into all kinds of issues with the new hardware. The issues kept bubbling to the surface but no one was really in charge of addressing the issues so they languished. The expert users kept insisting on enhancements that had not been agreed to and because we had to real requirements we kept trying to please them. And often their requests were in conflict with each other and there was no one to resolve that conflict. We usually ended up in a room with a lot of shouting going on. At the end of the year guess what? We were 99% complete again. The ship had sunk.
Management went ballistic, as you can imagine. The project manager kept insisting we just weren’t coding fast enough. That we were over analyzing. That learning a new language had slowed us down. This may have been true but the real problem was that we had no requirements to work from or to go back to when changes were made. In my mind that project was the epitome of chaos. That third year was the worst year ever. We worked ten hours days, often six or seven days a week, with no extra pay. I think we all just wanted to get this project done and finished.

So my question to you is this? Does everything look good on paper for finishing your project on time? If so, take a deeper dive into the requirements and make sure they are clear and traceable. Make sure the team knows what they are trying to do and who to take direction from. I think of the expression that “too many cooks spoil the pot”. Too many users involved in the development effort without defining the real requirements can spoil the project. Saying you have completed every milestone without having the deliverables to back it up is just delaying the inevitable. Good luck in steering your ship to a successful completion.

Why do I need a Requirements Management tool?

It’s no secret that poor requirements lead to poor quality products and that these projects are often filled with scope creep. The challenges with a document based approach to requirements are many, including the fact that it is difficult to keep them up to date in the ever changing of software development. Even if you have done a stellar job in gathering and documenting user requirements the task of managing the requirements has just begun.

Here are some primary reasons for using an automated Requirements Management tool according to Karl Wiegers www.processimpact.com article on Automating Requirements Management).

• Manage versions and changes. Most systems are released in an iterative (or Agile) fashion today. This means that requirements will have versions associated with the release. Being able to track changes and identify the impact of changes is controlling change and scope creep.

• Store additional information about the requirement in requirements attributes. There is so much more we need to know a requirement other than the requirements statement. For example: status of the requirements (in work, approved), priority, who requested it, test status). These are just a few suggestions.

• Link requirements to other system elements. In order to ensure all requirements are part of the product, all requirements are tested, changes are evaluated, etc. we need to be able to link requirements to other system elements.

• Track status. Think of being able to do create a list of all requirements that are not approved, all requirements that are not linked to lower level requirements, and all requirements that are not tested. These are the kinds of information that helps us really know the status of the project.

• View requirements subsets. Think of being able to view all high priority requirements that do not have a test method assigned. Or a security office who wants to review only the security related requirements. Being able to filter requirements to only include information the user is interested in seeing reduces the time required to review these requirements.

• Control access. You will want to make sure that business analysts can only modify user requirements; system analysts can only modify system requirements, and so on. Once approved, access to requirements must be limited so no further changes can be made without a review.

• Communicate with stakeholders. Notification of changes is essential to making sure stakeholders are aware of all potential changes. Most requirements management tools can assist in automatically providing this kind of notification.

For those of us who have used requirements management tools, it is difficult to imagine going back to doing that work on paper. And I believe there are few of us that would choose to go back to that method. I personally would take any requirements management tool over a document-based approach. However it is amazing to me that many organizations of all sizes continue to rely on document-based tools to manage their requirements. Using a Requirements Management tool is a required first step to getting control of requirements.

BY: Marcia Stinson

Your Customer Has Rights…. And Responsabilities

Let’s talk about what the customer has a right to expect from us. The customer can expect that analysts will speak the customer’s language and that we will learn about their business. This means we don’t throw a bunch of technical and design requirements at them and ask if this is what they want. Developers will explain their solution and will treat the customer with respect. Developers will NOT tell the customer how they should be using the system. And developers will not become defensive if the customer doesn’t think the proposed solution will meet their needs. The customer can expect that they will be provided opportunities to adjust the requirements as needed, within the defined process. They can expect that we will provide them with good faith estimates for the work. And, above all, they can expect a system that meets their functional and quality needs.

We are often focused on the customer rights, and so is the customer. But sometimes we forget to discuss with them their responsibilities. Often we assume they understand our process and know what their responsibilities are. As a result we don’t bother to tell them what we expect from them. Sometimes we skirt around the issue because we don’t want to “upset” them by telling that we have expectations about what we will receive from them. Sometimes we just don’t even think about it. So what are the customer responsibilities? Well, let’s be clear about what we expect from them.

If we are going to learn about their business they have to teach us. We expect customers to be precise when providing information and to make timely decisions when necessary. We expect customers to prioritize requirements and not just assume all requirements are a “high priority”. We expect customers to review documents that we give them and provide us with real feedback regarding the accuracy of our problem statement (user requirements). We expect customers to communicate changes as soon as possible and not wait until the last minute to provide them to us. Lastly, we expect customers to respect our requirements process. If we expect them to respect our process then we need to make sure we all know what that process is, including the change request process. If we cannot explain our requirements process, then how do we expect customers to understand out process? Being able to help customers understand the process is a critical piece of getting customers on board with our processes.

By communicating this information during the project kick-off meeting we are ensuring that we all understand our responsibilities to each other. It’s not just a one way street. Customers who tell us once what they want and then never communicate again will be the ones who say “I told you what I want, why didn’t you build it?” Analysts who document the requirements and never discuss them with the customer are the ones who say “We built what you told us, you didn’t know what you wanted.” Let’s remember there are responsibilities on both sides. And let’s make sure this is made clear to everyone on the project team. Think about your customers. Do they understand and respect your requirements process?

BY: Marcia Stinson

Practice Makes Perfect – Requirements Engineering Training

When I was young my mother decided I should take piano lessons. I was five years old and barely knew my ABC’s. My teacher was an older woman who sat down my first lesson and played Beethoven’s Moonlight Sonata for me. I was so impressed. I wanted to play that piece right away. An impossible goal, of course.

There was so much I had to learn before I could play that piece. I started with one hand (one hand, are you kidding????) and learned three notes on my first lesson. Then three notes on the left hand. Then five notes. I remember thinking this would take forever. And so on. It was many years of learning and practice before I was able to play Beethoven’s Sonata.

There were some key things I had to learn to do. First, I had to learn how to hold my hands properly. Then I had to learn to read music – a few notes at a time. Then I had to learn how to read the music and then play it. And, above all, I had to practice. I practiced at least an hour every day, more in the summer. And still it took five years for me to play that piece. My teacher was instrumental in that process. She taught me techniques. She corrected me when I made a mistake. I could not have learned to play the piano without her.

So let’s tie this to Requirements Definition and Management. Asking someone who’s never written or managed requirements to follow a robust and complex requirements process is like asking that five-year-old to play Beethoven’s Moonlight Sonata. And since we often don’t provide any training or mentoring, let’s ask them to learn to play that piece on their own. That’s what we are doing when we throw our analysts into a complex requirements process.

I suggest we consider training our analysts. Let’s stop thinking we all just “know how to do our job”. It isn’t true. We can learn to play that piece on our own. I would suggest instead of taking five years, it would have taken me ten years on my own. And so it is with our requirements engineers and analysts. We can let them learn on their own. Or we can give them some training, mentoring, and time to practice.

Of course, key to making this work (no pun intended) is having some kind of process defined that we use to train our analysts. I used to hate that “process” word, but it is important. Here are some suggestions for turning your new requirements analysts into expert requirements analysts quickly.

1. Provide training for your analysts around your specific process, using your requirements and deliverables, so the training is more real.Generic classes around requirements definition and management are great, but they must be in line with the processes you are following in your organization.If you are working with an outside consultant, expect that there will some effort in customizing the training for you.But it will be worth the investment.
2. Assign a mentor to your new analysts.Let someone who has “been there done that” and has the wounds and scars to prove it help the new analyst and show them the ropes.This will help eliminate that “tribal knowledge” thinking.Let them assist in elicitation sessions, review requirements documents with the analyst, and be a resource for them.
3. Let the analyst practice. That may not seem too practical. But don’t start a new analyst on a project that is critical to the company. Or one that has so much history and controversy around it that it will be difficult to move forward. Let them “practice” on a simple and well understood project to get their feet wet.

I believe the following statement is true.

“Good analysts are grown, no trained.”

Let’s grow some good analysts.

By: Marcia Stinson

The Mystery of Requirements

Many times in writing or reviewing requirements we tend to be a little “sloppy” in our writing. We need to remember that are not writing a mystery. What are some qualities of a good mystery novel?

• There is an underlying theme to the mystery.
• There are a lot of great characters involved.
• There is a clear setting where the story takes place.
• The final few chapters hold the climax of the story.

In other words, the author gives us clues all along, but it isn’t until the last few pages that we suddenly understand what the author has been trying to tell us all along.

Let’s take this approach with requirements. What makes requirements a mystery?

• There is no underlying theme. In other words, there is no clear reason, business or otherwise, why we are even doing this project.
• We get some of the characters involved, but we tend to miss some too. Making sure we have included everyone who is impacted by the project in any way is an important component.
• We’re not sure where the story takes place. To make a comparison, we don’t know where the product will be deployed or who will be using it. We need to know the setting.
• We are not persistent in understanding all of the clues the users give to us. There are lots of clues if we just pay attention. Users and stakeholders give us clues in many ways. Sometimes the clue may be in the way they respond to our questions in a nonverbal manner (i.e. rolling their eyes, crossing their arms, etc.). They may state assumptions about what they are thinking, yet another kind of clue for us. Sometimes a clue may lie in unspoken requirements that we have to try and get the users to verbalize for us. And sometimes the clues are in the form of a solution. When the users give us a solution they are really giving us a clue that they have a problem they are trying to solve. We must strive to understand what that problem really is.

The end of a mystery is exciting and gets our blood moving. We’re not sure until the last few pages that we really understood everything. If we manage projects in the same way we are in trouble. Software development should not be a mystery to us. We can’t wait until deployment to make sure that we solved the problem correctly. We want our requirements to be as clear and correct as possible from the beginning.

So here are some simple guidelines for writing requirements in a simple and concise statement, and removing some of that mystery.

• Every requirement should be a complete sentence. (i.e. a subject, verb and predicate with a period at the end) Remember our old English classes when we actually diagrammed sentences?
• Every requirement should describe clear success criteria. (The user shall be able to view the Audit Log Report.)
• Every requirement should state a single action and objective. Watch out for excessive use of “and” and “or”. For example:(If is the last Friday of the month and the payment is due on the 31^st, and if the 31^st is the last Friday of the month, then submitting the payment on that day after 6pm eastern time will result in a late payment.) I challenge to understand that one!
• A requirement should not have an escape clause. (The System shall determine the number of login attempts except when the user has clearly entered an incorrect username.)

Let’s make sure our requirements are not a mystery!

By: Marcia Stinson