Per Kroll Using use cases and scenarios makes the system functionality easy to understand and assists in developing, implementing, testing, and documenting the system. ProblemMany companies still document requirements as a list of declarative statements, often referred to as "shall statements." Such a list is often difficult for stakeholders to understand, since it requires end users to read through and mentally translate the list into a visualization of how they could interact with and use the system to do the work they need to do. This approach tends to place unreasonable expectations on the end users and causes them to have problems understanding what functionality will be delivered. It also focuses the team on development of atomic functions or requirements, rather than on development of collaborating units that address a usage scenario. As a result, applications developed in this way are often difficult to use and require more time for integration and testing than applications developed using user-focused requirements. This practice shows how to address the above problem by using scenarios and use cases to capture functional requirements. Nonfunctional requirements, such as performance, stability, or usability, can still be captured using traditional techniques. The practice also discusses user stories and work items and explains how scenarios and use cases are best developed in conjunction with, and used to drive, other development activitiesincluding user-interface design, design, implementation, and testing. BackgroundI just got a new cellular phone, and I was quite impressed with how easily I could find relevant information in the manual. The manual included the following sections:
When I pick up my phone, I am likely to want to take one of the actions described in the above list. The manual was thus organized around common usage models, or "use cases," to make it easy to find the necessary information. Good user manuals are often structured so that each chapter corresponds to a use case. However, the big difference between manuals and use cases is that manuals contain a lot of information about the user interface, whereas use cases purposely exclude user interface information because the user interface is the result of a large number of design decisions. Actors, Use Cases, and ScenariosA use-case model describes a system's functional requirements in terms of actors and use cases. An actor represents a type of user of the system or another system that will interact with the system. A use case describes how each actor will interact with the system. It addresses how the system addresses a goal of the user[11] by capturing a complete service of measurable value to the actor.
Let's look at an example. On the way home from work you realize you are short of cash. You see an ATM and walk up to it. What is the service you would like the ATM to provide? Since you need cash, you would probably like the service Withdraw Funds. Other common services are Transfer Funds (from one account to another) and Deposit Funds. These are three examples of use cases. In each case the end result will be something that you want, something of measurable value. However, not every action is a use case. For example, Validate Card is not a use case by itself, since it has no measurable value to you to know that your card was validated. Validate Card is a means to an end, not an end in itself.
The way use cases work is that we describe the functional requirements by describing how the end user (or external system) will interact with our system to get the service provided through the use case. In the case of Withdraw Funds, we describe step by step how you interact with the system to withdraw money. You can look at it as writing a chapter in the user manual up front, but without mentioning any details about the user interface.
It is essential to understand that a use case contains many scenarios. A scenario is a description of a specific instance of a use case. When you withdraw funds, you may do any of the following:
Each of these sets of events constitutes a scenario, and as you can imagine, a specific use case can have many scenarios. Important scenarios should be tested, and later in the lifecycle will have a one-to-one mapping to a test case. Work Items and User StoriesUse cases and scenarios are also used to plan and track progress, and to determine what should go into a release. Smaller scenarios, which often take one to three weeks to implement, are used in iteration planning, allowing you to decide which scenarios to implement, and to track progress within an iteration. Scenarios that are too big to be included in an iteration are broken down into manageable units, either by slicing the scenario more thinly (for example, by implementing the scenario with a simplified persistency mechanism and fixed data to simulate user input) or by implementing only one segment of it, such as the first third of the scenario (see Figure 4.9). Figure 4.9. Use Cases, Scenarios, and Work Items.A use case consists of a number of scenarios. As you determine which scenarios to implement in which iteration, you may need to divide them into thinner scenarios, or segments of scenarios. These scenarios, thin scenarios, or segments are called work items and are used to plan, estimate, and track work done within an iteration. The units that you are using for planning and tracking are called work items. Work items map to small scenarios, thin slices of scenarios, or segments of scenarios. Work items are, however, a generic concept that can also be used to plan and assign work not directly related to functional requirements, such as setting up a configuration management environment or delivering an internal training class. Work items are broken into more fine-grained work items as necessary.
A user story[12] is used by some in the agile community as an alternative to use cases and scenarios. A user story is used to briefly capture user requirements and to plan and track a project. As it should be possible to implement a user story within a single iteration, this effort should typically not take one person or a pair working together more than one to three weeks. If it requires more than three weeks of effort, the user story should be broken up into several smaller stories. In XP, user stories are written by users and should be no more than one or two sentences long. User stories are often loosely defined and typically map to a scenario, subsets of a scenario, or a supporting requirement, such as "the system should support Internet Explorer (on top of Fire-fox)"; see Practice 10: Prioritize Requirements for Implementation.
User stories are used in release planning meetings to determine what should be implemented in the next version of an application. They are also used in iteration planning meetings to determine what capabilities, that is, user stories, to implement in the next iteration. User stories can further be divided into developer tasks, and each user story should have associated test cases. During an iteration, track progress by identifying which stories have been implemented and tested. Applying the PracticeCapturing requirements from the user perspective requires you to do the following:
Let's have a look at each of these activities in turn. Identify Actors and Use CasesTo identify actors and use cases, take the following iterative steps, preferably in a workshop involving relevant team members and stakeholders:
Describe Use Cases and ScenariosWhen describing a use case, it is important to consider its two primary audiences: the stake-holders and the development team. Stakeholders leverage use cases to understand what services the system will provide to the users of the system. Use cases should therefore use a language that stakeholders easily understand and avoid drilling down to a level of detail that makes it hard for them to see which key capabilities are provided. The other key audience is the development team: developers and testers doing storyboards, design, implementation, testing, and user documentation. Use cases need to provide sufficient specificity and level of detail to be meaningful to the development team. It is also important to assess whether further detail is best expressed as additional text in a use case or is better expressed in the form of storyboard, test cases, or directly in the code.
It often takes just a few hours to produce a good draft of the most essential and typical use-case scenarios, though it generally takes considerably longer to complete the use case by detailing alternative flows of events within the use case. It is important to be clear on when it is sufficient to communicate requirements orally, versus also in writing. There is a cost to documenting: it takes time to write and to keep documents up-to-date. But there is often also a cost to not documenting: you may need to revisit decisions people have made and forgotten, or repeat what has already been discussed many times. A project may use several different strategies for detailing a use case.
You may find the following guidelines useful when documenting functional requirements in the form of a use case.
Using User Stories and Enhancement RequestsSome projects prefer user stories to use cases, because they provide less formalism. For small systems user stories work reasonably well, but they can easily become too numerous, especially for medium to large applications, and therefore hard to manage. In this case user stories end up providing you with a fragmented view of the application, as opposed to the goal-oriented view of a use-case model. If you use user stories for anything but very small systems, identify use cases and use them as a container for a number of related user stories. As appropriate, organize the stories in scenarios within the use cases. This approach will yield an end result that is somewhat similar to that described in the previous section, but using a less structured approach.
For existing application upgrades, you often get requests for support of additional user stories, that is, smaller extensions or improvements of current use cases and scenarios. RUP and OpenUP/Basic capture these as enhancement requests. As you decide to implement these enhancement requests, revise the use cases so that they are up-to-date. If you use strategy A or B above, you can do this quickly by adding one or two sentences to the use case impacted by each implemented enhancement request. Produce User-Interface Prototypes or StoryboardsEven though use cases should be easy to read for the casual user, you should consider complementing them with a user interface prototype or storyboard.[15] It is amazing how often users open up and provide a lot of useful feedback on the use case once they see a prototype. A picture often says more than a thousand words. . . .
It should, however, be emphasized that a use-case description is a functional requirements specification; you therefore do not want to include information about the user interface in the use-case descriptionwhich widgets to use, coloring, exact layouts of informationor about which design algorithm to use when implementing a capability, such as persistency or a list. If necessary, add references to user-interface prototypes, in case it is not obvious where to find them. Design decisions are better documented directly in the code, design, or user-interface prototypes. Putting design decisions in use cases makes these hard to read and rapidly obsolescent. Maintaining a clear separation between requirements and design also makes it easier to understand what are strict requirements and desires,[16] versus what are potential implementations of those requirements, so that you know when to go back to users to validate changes that are likely to be of interest to them.
Plan, Estimate, and Track Implementations of Use Cases and ScenariosWe need to break down requirements into manageable chunks that we can use for iteration planning, for bottom-up estimation of how long time it will take to do a job, and to allow us to track progress. Based on team size and iteration length, among other things, you want chunks that represent an effort ranging from a couple of days to a couple of weeks. OpenUP/Basic and RUP call these chunks work items, which map to scenarios or parts of scenarios. XP calls them user stories (see the Backgroundsection at the beginning of this practice). If you are using the Unified Process lifecycle, use cases and, to a lesser extent, scenarios are a primary vehicle used to scope the system in the Inception phase. Scenarios and work items drive development in earlier iterations, and as the application matures, the focus increasingly shifts to completing the use cases. Additional enhancements to existing use cases are captured as enhancement requests that are prioritized, and toward the end of the Construction phase they play an increasingly important role. For minor enhancement projects, enhancement requests take on a more important role throughout the project as a means of driving the work. Evolve Use Cases and Their Implementations Together
As always, keep the key principles in mind, especially Demonstrate Value Iteratively. It is easy to become too focused on perfecting the requirements, and many projects go under because the focus has turned to academic discussions on how to document requirements rather than on simply documenting the requirements well enough to enable successful implementation and testing of the system.
You need to evolve use-case descriptions in parallel with evolving storyboards, use-case realizations, the implementation of use cases, and the relevant test cases to validate the implementation of the use cases. Consider first documenting the obvious parts of a use-case description, creating an initial storyboard for the use cases, and then implementing and testing the most stable parts of the use cases. As you walk through the partial implementation, you are likely to get a lot of invaluable feedback and hence a much better understanding of how to complete the use case. Leverage Use Cases When Writing User DocumentationAt the beginning of this practice we mentioned that a good manual should be structured along use cases. Typically, one user manual should be written for each actor and one chapter for each use case. This strategy ensures that the manual is structured according to major usage scenarios. For online help, you should make sure that the use cases correspond to major topics that are easy to find in the Table of Contents.
Other MethodsAll agile methods emphasize the user perspective, but they achieve this objective in different ways. A key aspect that they all have in common is including the customer in the project team. XP documents the requirements in the form of user stories. These user stories are written down, preferably on an index card, using only a one- or two-sentence description. XP then relies on verbal communication between the customer and other team members to ensure that detailed information about the user stories is understood. Test cases for the user stories will provide more guidance on the user story and how it should be tested. The advantage of user stories is that they are easy to understand and to prioritize. They can be implemented rapidly, and daily progress against a set of user stories is easy to measure. The disadvantage of this approach is that you can be overwhelmed by too many user stories and easily lose track of the big picture. Scrum does not prescribe how requirements are to be documented, but it is specific about organizing all requirements, change requests, and defects into one list called the Product Backlog. This list is prioritized and drives development in each iteration. RUP and OpenUP/Basic leverage Scrum's concept of the product backlog and also recommend the documentation of requirements as use cases and scenarios. Scenarios and use cases focus on what the user wants to accomplish, which can easily be missed when focusing too much on user stories. Many similar scenarios can be organized into one use case, and by using alternative flows you can minimize the overall amount of text in a use case relative to having many scenarios. Scenarios, or parts of scenarios, are mapped to work items, similar to a user story, which are used as a planning, estimation, and tracking unit. Scenarios and work items drive development in earlier iterations, and as the application matures, the focus is increasingly on completing use cases. Levels of AdoptionThis practice can be adopted at three different levels:
Related Practices
Additional InformationInformation in the Unified ProcessThe requirements discipline in OpenUP/Basic provides guidance on work items, scenarios, and use cases. RUP's requirements discipline adds guidance on more types of requirements, including stakeholder requests and supplementary requirements, as well as on using more disciplined approaches leveraging requirements attributes, requirements plans, and requirements management tools. Additional ReadingFor detailed books on use cases, we recommend the following:
For books that provide you with an understanding of how use cases fit with other lifecycle activities, such as design, implementation, and testing, see the following:
|