Practice 9. Describe Requirements from the User Perspective

Per Kroll

Using use cases and scenarios makes the system functionality easy to understand and assists in developing, implementing, testing, and documenting the system.

Problem

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

Background

I 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:

Prepare your phone for use
Get to know your phone
Make and answer calls
Use the phone book
Use voice mail
Work with the call log
Customize your phone

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 Scenarios

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

^[11] See Cockburn 2001.

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.

Use cases describe how the end user will interact with our system.

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.

A scenario is a description of a specific instance of a use case.

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:

Withdraw $100 from Checking, with a receipt being printed.
Withdraw $40 from Savings, with no receipt being printed.
Try to withdraw $30 dollars from Checking, only to be instructed that you need to withdraw a multiple of $20. You then try to withdraw $40, only to be informed that you do not have sufficient funds in your account.

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 Stories

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

Work items are used to plan and assign work.

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.

^[12] Beck 2004.

A user story is used to briefly capture user requirements and to plan and track a project.

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 Practice

Capturing requirements from the user perspective requires you to do the following:

Identify actors and use cases.
Describe the use cases and scenarios.
Produce user-interface prototypes or storyboards.
Use user stories and enhancement requests appropriately.
Evolve use cases and their implementations jointly.
Plan, estimate, and track implementations of use cases and scenarios.
Leverage use cases when writing user documentation.

Let's have a look at each of these activities in turn.

Identify Actors and Use Cases

To identify actors and use cases, take the following iterative steps, preferably in a workshop involving relevant team members and stakeholders:

Step 1. Identify as many actors (remember, actors represent both users and external systems with which the system interacts) as you can. Write a one-sentence description of each actor.
Step 2. Associate each actor with use cases, capturing the actor's goals with using the system by providing a brief description of the use case. Provide a use-case diagrama graphical depiction of your use cases and actorsto provide a simple overview of what the system is about and to act as a useful reference throughout the project.
Step 3. For each use case, determine whether it requires interaction with other users or systems. This will help you identify additional actors. Continue to go back and forth between finding actors and use cases until you think you have identified enough to understand the scope of the system. You most likely have not gotten them all, but what you have should be good enough at this stage.
Step 4. Write a sentence or two describing each actor,^[13] and outline a couple of paragraphs for each use case. In this way you can avoid a situation in which each person has his or her own interpretation of what role the actor corresponds to and what the use case entails. Determine whether you need to come up with a few more use cases to cover all the functionality needed.
^[13] For applications with a strong focus on usability, the description of an actor may later be evolved to a description of one or several personas; see Cooper 1999.
Step 5. Create a glossary containing the key "items" dealt with in the application, or add items to a glossary if you already have one. Note that a glossary should ideally be organized by application family, so that all applications within a certain domain use the same one (for example, the domain of financial services, the domain of insurance). Review key items that the system is dealing with, that is, the business entities, and make sure that a use case describes how each business entity is created, maintained, and deleted.
Example: For an insurance application dealing with policies: Do you have a use case that describes how to set up a policy? How to make changes to a policy? How to cancel a policy? This is a great way of discovering holes in your use-case model, and spending only 30 minutes on this activity often goes a long way. Note that you typically should not create a use case for each business entity; rather, you will often have a many-to-many relationship between business entities and use cases managing some aspect of that entity's lifecycle.

Describe Use Cases and Scenarios

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

When describing a use case, consider its two primary audiences: the stakeholders and the development team.

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.

Strategy A: use for small-project, collocated teams, when the same person does requirements and development. Briefly outline the steps within each scenario, and keep the description of each step to no more than one or two sentences.^[14] Any additional information is transferred through discussions and documented as storyboard, test cases, or code. This allows you to keep the use case to no more than two pages.
^[14] Cockburn 2001.
Strategy B: use for larger, more complex projects, distributed teams. Briefly outline the steps within each scenario, and keep the description of each step to no more than one or two sentences, as in strategy A. For many of the steps, you will have a lot of additional information to transfer to stakeholders, users, analysts, developers, testers, information developers, and so on.
Document this additional information within the use-case description, but mark it as "transient" information, that is, information that does not need to be maintained. This can be done simply by setting transient information in italics or a distinct font or tagging it in some other way. Your use cases may grow to two to six pages, but they can be much longer for systems with complex sequencing, such as telecom systems, or much shorter when there are limited sequencing and few business rules to be applied, such as viewingbut not updatinga limited set of information. Once the use case has been implemented, the transient information is removed.
This strategy is suitable for larger or more complex projects, or when you have a distributed team, or when team members cannot spend as much time face to face as is required with the previous strategy, perhaps because of different work schedules, constraints due to travel, or competing assignments.
Strategy C: use for projects requiring high ceremony and documentation. Use the same techniques as in strategy B, but maintain the additional information, rather than treating it as transient.
This strategy is appropriate for projects requiring more ceremony, such as those concerned with compliance, contractual or other constraints, or building safety-critical systems.

You may find the following guidelines useful when documenting functional requirements in the form of a use case.

Identify the steps in the flow of events for the most common scenario of the use case to which you are referring. These steps should capture the basic flow of events, or the "Happy Day" scenarioa scenario in which everything goes as expected. In the banking example above, that could be Transfer Balance from Checking to Savings when there are sufficient funds.
Describe each of the steps for that scenario: (1) validate card, (2) select account to transfer from, (3) select account to transfer to, (4) select amount to transfer, (5) log transfer, and so on. Use the level of detail consistent with your team's chosen strategy (A, B, or C discussed above). Note that you may apply different strategies for different use cases, some of which may be more critical than others.
For each of these steps, identify all the things that could go wrong, that is, all exceptions to the Happy Day scenario (see Figure 4.10). Document these alternative flows of events as "If XX, then YY…" and list them as sub-bullets under their respective steps.

Figure 4.10. Structuring of Flow of Events.

The typical structure of a flow of events: the straight arrow represents the basic flow of events, and the curves represent alternative paths relative to "normal." Some alternative paths return to the basic flow of events, while others end the use case. A scenario is a combination of main and alternative flows from start to finish through a use case.

(Reprinted from Kroll 2003.)
Continue to describe each alternative flow of events with the level of detail consistent with your chosen strategy. If the alternative flow of events becomes longer than a paragraph, place it in a separate section toward the end of the use-case description and reference it from the step in which it previously was described. This restructuring makes it easier to distinguish the Happy Day scenario, since the use-case description would otherwise be chopped into too many long parallel flows.
If you have a lot of business rules, define these rules outside the use case in a separate requirements document. Within your use-case description, reference in each section the business rules that should be applied. This way of handling business rules is especially good if the same rules are referenced from many different use cases, or even applications.

If you have a lot of business rules, define these rules outside the use case.
Add preconditions and postconditions, that is, clarify what the use case expects and what it delivers, if not obvious from the use case steps. A precondition is the state of the system that is required before the use case can be started. A postcondition is the state the system is in after the use case has ended; see Bittner 2002 and Cockburn 2001.

Using User Stories and Enhancement Requests

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

User stories provide a fragmented view of medium to large applications.

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 Storyboards

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

^[15] See Kroll 2003.

Consider complementing use cases with a user interface prototype or storyboard.

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.

^[16] Most "requirements" are not really requirements, that is, "something mandatory or obligatory," but rather something negotiable that it is desirable to implement; Beck 2004, p. 44.

Plan, Estimate, and Track Implementations of Use Cases and Scenarios

We 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

It is easy to become too focused on perfecting the requirements.

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.

As you walk through partial implementations of a use case, you get invaluable feedback.

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 Documentation

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

Write one user manual for each actor and one chapter for each use case.

Other Methods

All 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 Adoption

This practice can be adopted at three different levels:

Basic. Identify scenarios and use them to plan, estimate, and track iterations. Optionally, group scenarios under folders representing use cases.
The basic practice of capturing scenarios keeps the process light, while making it easier to prioritize what should be done in which iteration.
Intermediate. Describe and capture use cases textually. Identify key scenarios, but in the context of use cases. Capture alternative flows of events and failure scenarios using strategy B (see the section Describe Use Cases and Scenarios on page 176), that is, using one or two sentences to describe each step in the flow of events and marking additional information as transient. As appropriate, place detailed information in user-interface specification, designs, code, or test cases rather than in use cases.
As long as you remember to document "just enough" information to allow rapid progress while clarifying how the system should work, the intermediate practice will take you down on the process map. Capturing the key capabilities that are to be implemented makes it easier to iterate, since you can more easily carve out small chunks of capabilities to implement and test within an iteration. The team will, however, need more knowledge and discipline to manage more structured use cases effectively.
Advanced. Describe and capture use cases in clearly defined testable chunks (scenarios, alternative flows of events, or pieces thereof called user stories), each as a separate requirement. For each requirement, track attributes, such as an estimate of how long it will take to implement the requirement, who will implement it, traceability to test cases, and so on.
The agile community often recommends storing these requirements (user stories) on index cards for easy access and sorting. This method has the additional advantage of discouraging spending too much time on each requirement, but it may also lead to time being wasted on oral explanations (and repeat explanations) of what is meant by each requirement by not providing a sufficient level of detail. Our experience is that requirements management tools built to manage database records are more effective for projects that demand more than a few staff months of effort. This method also allows you to view individual requirements in the form of complete scenarios and use cases.
The advanced practice of dividing a use case into small, testable requirements adds ceremony. Add only the most essential attributes and information, and leverage the most suitable technology to minimize the level of ceremony. Assuming that you avoid dragging along a lot of irrelevant information, this detailed information should have no material impact on iteration length.

Related Practices

Practice 8: Understand the Domain describes how to document key aspects of the problem domain to minimize communication issues and to increase every team member's understanding of the problem domain. A good understanding of the domain is crucial to achieve concurrence on the requirements.
Practice 10: Prioritize Requirements for Implementation shows how to determine which requirements should be addressed in early iterations to drive the architecture and to mitigate key risks.

Additional Information

Information in the Unified Process

The 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 Reading

For detailed books on use cases, we recommend the following:

Kurt Bittner and Ian Spence. Use Case Modeling. Addison-Wesley, 2002.
Geri Schneider and Jason P. Winters. Applying Use Cases: A Practical Approach, Second Edition. Addison-Wesley, 2001.
Alistair Cockburn, Writing Effective Use Cases, Addison-Wesley, 2001.

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:

Per Kroll and Philippe Kruchten. The Rational Unified Process Made Easy: A Practitioner's Guide to the RUP. Addison-Wesley, 2003.
Ivar Jacobson, Grady Booch, and James Rumbaugh. The Unified Software Development Process. Addison-Wesley, 1999.
Peter Eeles, Kelli Houston, and Wojtek Kozaczynski. Building J2EE™ Applications with the Rational Unified Process. Addison-Wesley, 2003.