Introduction to Gathering Requirements and Creating Use Cases

Studies indicate that between 40% and 60% of all defects found in software projects can be traced back to errors made while gathering requirements.

This is huge! Finding problems while they are just in the planning stages is MUCH easier to deal with than finding them after the code has been written. So, how can developers avoid these errors and create a solid design for their software? This article will describe various methods for gathering software requirements and writing Use Cases - the first two steps in the software development process.

Imagine you are about to build a house…

You're not sure exactly what you want to build, but you know you want a “nice” house, a “big” house, and you know that you have a budget of $200,000. So, the first thing you do is go to the lumberyard and purchase various materials - lumber, windows, doors, drywall, roofing and cement blocks. You get the materials delivered and you grab the first 2x4 and start building the house. Blueprints? Who needs them? Heck, you know what you are doing and you've been inside a lot of houses right? This notion, of course, seems absurd, but that's exactly the way most software applications are built today. Developers talk to the client for a few minutes, get a general idea of what the client needs, and then sit down at the computer and start to code…

Wait a minute! There are better ways to do this! You may want to say, “But I don't have time to figure all these things out, I've got to get this done! The deadlines are tight on this project!” Before you do, take a moment to consider how much quicker it is to fix a problem early in the process, rather than later. The earlier you discover the problems, the less time is wasted and the fewer things are affected. If we take a look back at the house example, think about this: how much quicker and cheaper would it be to change the blueprint and build a two-story house rather than to build a one-story house and then rip off the roof to add the second story? The typical outcome of incomplete requirements is a huge gap between what the developers think they are supposed to build and what the users think they will get. This, of course, makes the software take longer to build and drives the cost up.

So, let's take a look at what exactly software requirements are and what techniques we can use to collect them.

Requirements

There are basically two types of software requirements - Functional and Non-Functional. As the name implies, Functional requirements describe the functionality of the product. They describe exactly what tasks the software must perform. Functional requirements define the scope of the system, the product boundaries, and its connections to adjacent systems. Functional requirements also define the business rules. Business rules are the rules that the system must conform to, based on the individual business. This includes defining the data that must be tracked. The business rules are the most important type of functional requirements and most of your requirements will be of this type.

Non-Functional requirements describe the look and feel of the system. This includes the visual properties of the system, its usability, and the performance requirements - how big, how fast, etc. Non-Functional requirements also include the product's intended operating environment and any maintainability, portability and security issues. Non-Functional requirements also include cultural and political issues as well as legal requirements that the software must conform to.

It's important to point out that various sources, such as books and web sites, describe the different types of software requirements using other categories, often with contradictory terminology. The important part, however, is not which category the requirements fall into, but that all the requirements in the business process have been identified and documented.

So, now that we know what types of information we should be collecting, let's take a look at the characteristics of good requirements. Good requirements have the following attributes. They are:

• Complete - they very thoroughly describe the criteria
• Correct - they are accurate and true
• Feasible - they can be accomplished and individual requirements do not contradict each other.
• Necessary - they are truly needed for the system to function properly and they are really what the client wants.
• Prioritized - in the case that not all parts of the system can be implemented at the same time, it's important to be able to distinguish “absolutely necessary” from “nice to have”.
• Unambiguous - they are clear and cannot be misinterpreted
• Verifiable - once implemented, it can be confirmed that the system has met the requirement through observation and testing

Looking at the above list, it's obvious that quality and accuracy are extremely important. One way to assure quality is to create a single checkpoint that each requirement must pass through. Thus, a single person or a group of people must eventually individually approve every requirement no matter where it originated. Having a single quality checkpoint is especially important in large or complex projects. In addition, it's vital to make sure that the requirements are not too general, and that they are comprehensive and completely clear. Keep in mind that the person collecting the requirements might not always be the same person who will be writing the actual code.

So, where and how do we find out about the requirements for a system? The best places are from:

• Domain Experts - people who are very knowledgeable and work in the area of the system that is being built
• Users - people who will actually be the ones using the system once it's built
• Existing processes and programs - both manual processes and existing programs
• Find out the limitations of existing systems and software
• Find out where the users' time is spent
• Find out what they like and don't like
• Sit down with the users WHILE they are performing their tasks. Be sure to ask questions to get a clear idea of what they are doing.
• Review similar software programs - if there is a similar or competing program, this can be a great resource

It's important that you set up meetings with these people and interview them in order to extract the information. This, of course, is not always an easy task, depending on the people involved and how well they can communicate about what they do and how they do it. More information about dealing with the customer while collecting requirements can be found in the “Customers vs. Code” column in this issue of Component Developer Magazine.

So, now we know what information we are looking for and we know where to get it. The next items we'll discuss are the various methodologies for collecting requirements. These techniques include cards, simple requirement lists, matrices and templates, as well as complex software programs for requirements management. Often, a combination of techniques works the best, since each method has strengths and weaknesses.

One methodology for collecting requirements is to write each requirement on a separate 5" x 7" index card. Using these cards is an excellent way to begin the requirements collection process, and the cards have some other advantages, as well. They are a fast and easy way to group, reorganize and discard ideas. Additionally, they can easily be sorted and distributed among different people or groups. There are several different techniques that involve using these cards - CRC cards, XP Story Cards and Volere Snow Cards.

With CRC cards, the Class, Responsibility and Collaboration for each requirement are recorded. Using the requirement, identify the Class by finding the noun in the statement. The nouns usually indicate the classes in the system. The Responsibility is anything the class knows or does, and can usually be identified by the verb in the requirement statement. The Collaboration occurs when the class needs information it doesn't have - it describes the interaction between other classes and objects.

XP Story Cards is a technique used in Extreme Programming. This involves the customer (not the programmer) writing a short, simple story on each card. Each card should hold approximately one week of programming work for a single programmer.

Finally, Volere Snow Cards are cards that are preprinted with a variety of information about each requirement (see Figure 1). See the sidebar for web site addresses to obtain information about each of these processes.

Figure 1 - Volere Snow Cards

Another technique for collecting requirements involves simply keeping a list of requirements. As this list grows, it is grouped into logical elements from the business domain. For example, you may have requirements that fall into the following categories: customers, products and billing. Once this list has been compiled, the next step often is to create a Requirements Trace Matrix. This matrix simply takes the list of requirements, grouped by category, and puts them into a matrix that has other information (see Figure 2). One effective technique is to store this information on a system that can easily be shared and modified by each team member. Office Collaboration (part of Microsoft Office) or a Wiki Web (see sidebar) is perfect for this.

Figure 2 - RequirementsTrace Matrix

Finally, a third methodology involves using a predefined template containing various groups of information about the project. These templates are extremely useful, since they insure that all the necessary information has been gathered and that nothing has been overlooked. Two such templates are the Vision and Scope Document and the Volere Specification (see sidebar for web links). These templates contain extensive information about the project - the actual requirements are just a small portion. In addition to sections for various types of requirements, they also include items such as the vision of the solution, the scope of the project, the product constraints, success factors and more. If the list of requirements is large, it's useful to create separate documents, perhaps using requirement trace matrices, for the requirement portion of the template and reference these external documents within the template.

As we've seen, there are many different ways to collect requirements. The important thing is to find a technique that works well for you.

Use Cases

So, now that we have a complete organized list of requirements, I guess we're ready to start coding, right? Whoa, not so fast! The requirements really just give us an outline of what we are trying to build. Use Cases are the next step in the design process. Use cases integrate the requirements into a comprehensive package that describes the interaction of the user with the system. So, what exactly are Use Cases, and how do we build them?

Ivar Jacobson first introduced the Use Case and the Use Case Diagram as an important application analysis tool. Ivar Jacobson is one of the “three amigos,” who, along with Grady Booch and James Rumbaugh, are credited with creating the Unified Modeling Language (UML). Use Cases are text documents, written in plain English, which describe a scenario in which an “Actor” interacts with the “System”. The name “Actor” is slightly deceiving since an actor isn't always a person. Often, the actor is simply another computer system or other hardware. The actors are not part of the system, but are outside of it. They are the ones interacting WITH the system. The Use Case should describe the interaction between the actor and the system - what the actor does and how the system reacts. Be careful to make sure the Use Case describes only how the system reacts. While writing the Use Case, don't worry about the implementation of the system or the exact interface it will have. An application will be described by many Use Cases (the exact number will, of course, depend on the size and complexity of the system).

A quick search in your browser for “Use Case Template” will yield many different template styles. Find a template that best captures the requirements for your application.

Use Cases begin where the Requirements Gathering process leaves off. The requirements determine what Use Cases the system will have, and many of the requirements will become the business logic in the Use Cases. Of course, as Use Cases are being developed, you will have many questions - this is where the Domain Experts and Users again play an important part in the software design process. Other Stakeholders will also have valuable input. Stakeholders are people who have an interest in the system (perhaps the owners of the company that the system is being designed for), but unlike the Users, Stakeholders may not have any direct contact with the system being built. Use Cases are also extremely valuable since the stakeholders of the application can easily understand them. Therefore, they help to eliminate misunderstandings about the scope and functionality of the system.

Basically, there are two parts to developing Use Cases - the text document and the accompanying UML diagrams. Most developers begin the process by filling out a Use Case template for each of the Use Cases.

Perhaps the easiest way to understand how to create a Use Case is by looking at an example. Let's consider a very simple web application that allows a user to go to a web site and purchase movie tickets. First, we'll gather the requirements of the system, and from this requirements list, we then can fill out the Use Case template.

Let's examine each section of the Use Case and discuss its function. The Overview section, as its name implies, is simply one or two sentences describing the overall scenario that the Use Case covers. In this example, as seen in Figure 3, the Overview would be: This scenario describes a Customer purchasing movie tickets online. The Notes describe any relevant information the reader should know about the Use Case. In our case, a note may be: “The customer must be able to access this site using any web browser.”

Figure 3 - Use Case Template showing the Overview, Notes, Actors and Preconditions

The Actors section lists the actors involved in the scenario. Remember that the actors are not always people, but instead may be other programs, systems or equipment. In our example, the actor is simply the customer who is buying the tickets. Alternatively, you can name the actors (like “John” or “Jane”) and then use the name in the Scenario.

The Preconditions list any events that must happen prior to the event that the use case covers. In our example, the precondition is that the customer has navigated to our web site, researched the movie she wants to see, and is now ready to order tickets.

The Scenario is the most important part of the Use Case; in fact, all the other sections of the Use Case are there to support the Scenario. There are several different techniques for presenting this information, but I think the easiest and clearest way is how it is shown in Figure 4 - in a tabular format with two columns. (Note that Figure 4 shows only the first 3 steps in the scenario. The scenario shows step-by-step the interaction between the actor and the system. The first column shows what the actor does, and the second column shows the reaction of the system. A common mistake is shown in Figure 5. Each Action MUST HAVE a System Reaction. If a given action does not elicit a response from the system, then the Action should simply continue until a system reaction is evoked, as shown in Figure 6.

Figure 4 - Use Case Template showing the Scenario section

Figure 5 - Use Case Scenario showing an INCORRECT action since it doesn't cause a reaction

Figure 6 - Use Case Scenario showing the corrected way to structure the information so that each Action causes a Reaction

Looking at Figure 7, you will see that the next section in the Use Case template is the Scenario Notes. These are notes about any of the information covered in the Scenario. This is also a good place to put any questions about the Scenario. Post Conditions cover anything that must be addressed after the Scenario ends. For example, these may include anything the system needs to do to “reset” itself, or where the system takes the user next. Exceptions detail any rare business situations that would affect the Scenario. Often times, Exceptions start with "The above scenario doesn't apply when…". Required GUI and GUI Sketches are where interface sketches or proof-of-concepts are shown. If you are updating an existing program, screen shots of the existing program may be put here. In the Dependencies and Relations section, you should list any related Use Cases. In our example, we have two related Use Cases.

Figure 7 - Use Case Template showing the Scenario Notes, Post Conditions, Exceptions, Required GUI and GUI Sketches, and Dependencies and Relations

For creating Use Cases, a tool that allows collaboration among the designers, as well as the ability to link documents, is extremely beneficial. For these reasons, both the Wiki Web and Office Collaboration are good tools for creating Use Cases.

Use Case Diagrams

With a Use Case Diagram, the relationships between the Use Cases are obvious. As seen in Figure 8, the Actor is represented as a stick figure (whether an actual person, or not), and each Use Case is represented as an oval. The arrows show the relationship between the Actor and Use Cases and between the various Use Cases.

Figure 8 - Use Case Diagram

There are various drawing tools that enable drawing Use Case Diagrams, as well as other UML diagrams. Three of the most common are Visual UML, Rational Rose and Visio. See the sidebar for links to these products.

Conclusion

So, now we've explored collecting requirements as well as creating Use Cases. I'll be the first to admit that collecting requirements and writing Use Cases can be really tedious, especially for a large project. However, I see it as a necessary part of the development process, and I think that once you get comfortable with these design processes, you will view them as a necessary tool for software design. Good planning is an essential component for producing high quality software. It's one thing to just sit down and write a stand-alone application without good planning, but writing a well designed, object oriented, flexible, COM/COM+ scalable Web application without proper planning is almost impossible!

Often, programmers, as well as customers, feel like they aren't being “productive” when they are working on the design instead of producing code. However, applications that are well-planned and built with a solid design are actually less time consuming to build, more flexible and scalable, and easier to maintain than those built by trial and error. An added benefit is that after requirements have been collected and Use Cases have been produced, it is much easier to accurately estimate the cost of programming the project.

The final step in the design process is producing UML models. We will discuss this in the next issue of Component Developer Magazine.