You have decided that writing a set of use cases will help you and your stakeholders understand a system's functional requirements.

In a special session before the U.S. Congress, President John F. Kennedy made the challenge “that this nation should commit itself to achieving the goal, before this decade is out, of landing a man on the moon and returning him safely to earth.” These words became a mantra to NASA and much of the nation. The scope of the project was enormous, and presented many technological, manufacturing, and management challenges. Inspired by President Kennedy's dream, the United States spent over 25 billion dollars (that's close to 100 billion by today's inflated standards) and used the services of several hundred thousand people for eight years. The well-focused vision was realized on July 20, 1969, as people all over the world watched Neil Armstrong step onto the moon and utter the famous words, “That's one small step for [a] man . . .”

Effective use case writers have a clear vision of the system's purpose and make sure that everyone involved shares that vision.

Time pressures can encourage people to start developing a system prematurely, basing their work on erroneous assumptions. Getting them back on track can be expensive. Often, builders simply enumerate the system's basic services, creating use cases without understanding their value to the actor requiring the service. This approach fails to reflect accurately the users' needs and can paradoxically result in features that are unnecessary or deficient. Many of the so-called CRUD (Create, Read, Update, and Delete) use cases originate from a lack of a clear vision.

Builders have a natural tendency to expand the scope of the system. Without some guiding principle that can be used as criteria for evaluating and scrubbing features, there is a danger that the development team will expand the scope of the system. The vision provides a mechanism for removing vague, ambiguous, or poorly defined requirements from the scope of the project. It is an objective filter for scrubbing requirements, and helps to define what is in or out of the system's scope.

Stakeholders have competing visions. There are usually competing visions of the actors' needs and responsibilities, and stakeholders often have very little knowledge to help select the most appropriate vision of the system. Most projects are under time pressure and cannot simply evaluate a countless number of alternatives. Team members must begin to limit the solution space quickly. If there is no clear vision, then project participants may substitute their own vision for the project, which may conflict with the corporate mission. For example, without a vision, the software developers may create their own vision for the product that emphasizes scalability and flexibility in the software architecture. Although these are highly desirable architectural characteristics, they may conflict with the corporate need to deploy a system quickly and cheaply.

People in the trenches don't know what the goal of the project is. An interesting experiment on larger projects is to go around and ask the participants why they think the project is important. If you're fortunate, most people will understand how their specific piece of the project contributes to the overall project. But does anyone understand what the goal of the project is beyond making money or reducing costs? What does the system allow its users to do that they couldn't do before? Why is this important? Simply, is it clear to all project participants why someone is willing to pay money for the system?

People don't communicate. Despite an organization's best efforts to encourage communication—by replacing private offices with cubicle hell, for example—there remain many barriers to informal communication in any organization. The larger the organization, the stronger these barriers are. When there are strong barriers to informal communication, then the formal communication channels must be strengthened.

Therefore:

In the vision statement, include the following:

Maintain consistency in the vision by making a small team of people responsible for creating the vision (SmallWritingTeam [p. 31]). A characteristic of many successful projects is the appointment of a single person who champions the vision of the system and is responsible for maintaining the consistency of that vision. This responsibility usually falls on someone in a marketing role, such as the product manager. This person must also actively communicate with all members of the development team, to ensure that they share the same interpretation of the vision.

Validate the vision and seek support for the vision by obtaining advice from those who will be affected by the system (ParticipatingAudience [p. 35]).

Strengthen and constrain the vision by clearly specifying what is outside of the system and what is part of the system (VisibleBoundary [p. 86] and ClearCastofCharacters [p. 90]).

Ensure that the vision is supportive of the stakeholders' mission and shows up in the UserValuedTransactions (p. 95). Even a truly excellent system vision will fail if it defines a purpose that works against the organization's mission.

Finally, when there are changes to the vision, make sure that all project participants learn about the changes immediately.

Examples

Wings Over the World

There are few things short of an extinction event—like a huge asteroid hitting the Earth—that can derail your project as quickly as the lack of a shared clear vision. Most modern methodologies emphasize the need for a vision statement or document. Unfortunately, when people produce a typical vision statement, they do so only to satisfy the requirements of the methodology or to fulfill a contractual obligation with the client. The vision is rarely shared or clear.

Consider what happens when our long-suffering consultant asks Ahmed, “Why are you building this system?” Ahmed answers by itemizing the technology that's being used to implement the new system. After further probing, Ahmed offers only, “Well, to allow people to book their travel on-line.”

It is hard to believe that the company's directors would launch a project simply to “allow people to book travel reservations on-line.” (Maybe this was acceptable during the dot-com bubble, but we certainly hope it is not the case anymore.) Why is this feature important to the mission of the company? Does the company see itself as a market leader, trying to increase market share by offering clients the option of booking on-line? Is it playing catch-up with its competitors to preserve market share? Or is it trying to reduce the cost of bookings in a highly competitive marketplace?

By failing to communicate the objectives for the system to all project participants, the directors are creating a void that others may fill with their own agendas. Technical teams are notorious for this.

Ahmed is envisioning a high-performance, scalable, Web-based system. There is nothing sinister in this practice, it's just human nature. Maybe Ahmed's vision happens to align with the corporate mission. But what if the company is playing catch-up and needs to deploy a system quickly and cheaply to stay abreast of its competition? Then Ahmed's vision may run counter to the corporate needs. Without a SharedClearVision, the development team will create one based on their core belief: reliability, scalability, and expandability are the important characteristics of a high-quality system. Without a clear vision for the system, developers will bias their design efforts toward these goals rather than those of the overall organization.

What is an appropriate vision statement for the Wings Over the World project? See Figure 4.1.

Figure 4.1. The Wings Over the World vision statement

In Figure 4.1, we have something. We won't claim that it's perfect, but we do at least see the corporate vision for the system. This statement will help structure our thinking as we begin the process of discovering the use cases.

Fortunately for Ahmed, this corporate vision seems to support his technology vision.

Automated Railway Signaling

The Vehicle Control Center (VCC) guides automated trains for city mass transit systems in Canada. The original software for this system was nearly twenty-five years old, and it was becoming difficult to find replacement parts for its aging sixteen-bit minicomputers. Finding programmers who could, or even wanted to, program them was also difficult. Furthermore, the capacity of the system was fast approaching its design limits. With rapid growth in the mass transit marketplace, it was time to consider replacing this tried-and-true legacy system.

Replacing such legacy systems is fraught with risks. According to Frederick Brooks (1995), the second system is the most dangerous system a person can ever build, because it provides an opportunity to release all the pent-up desires to fix the perceived shortcomings in the first system. Naturally, this desire translates into “gold plating,” adding features of little value that make the product look better. However, the VCC replacement project organizers controlled this desire with a well-defined project vision statement (see Figure 4.2).

Figure 4.2. The vision statement for the Automated Railway Signaling System

This vision statement clearly states what the project's participants could and could not do, effectively preventing gold plating. Possibly the most important statement in this vision is the last statement. Rigorous enforcement of that final sentence led to the success of the project (Adolph 1996).

Mobile Dispatching

Contrast the Vehicle Control Center legacy replacement project with another one whose aim was to replace a mobile dispatch system. The circumstances surrounding the decision to replace this legacy system were similar to those for the Vehicle Control Center; however, the results were different. A year after the project's inception, it was cancelled without delivering anything of worth (Adolph 2000).

The project began with a well-defined vision statement, shown in Figure 4.3.

Figure 4.3. The vision statement for the Mobile Dispatching System

The “Lowers software maintenance costs” clause was probably the spark that contributed to the project's explosive downfall, because management and development understood it differently. Management believed that the clause meant reducing the time it took to perform standard system customizations for a client. The developers, however, felt that it meant completely rewriting the dispatch system using leading-edge technology. Both sides had a clear vision, but it wasn't a shared one—not even close.

Checkpoint Charlie, Berlin

You have a SharedClearVision (p. 80) for a system.

The late 1950s was probably the golden era of the so-called B-films. One of the films that all connoisseurs love is the 1958 science fiction film The Blob. In this movie that launched Steve McQueen's career, a group of teenagers discovers an alien creature from outer space that has no form or shape. The creature grows rapidly as it absorbs everything and everyone around it. As expected in a film of this genre, the teenagers attempt to warn a doomed town of the danger it faces, but no one believes a bunch of kids until it's too late.

Few other films have been used as extensively as a metaphor for the dangers of uncontrolled or unmanaged growth. The Blob has symbolized everything from urban sprawl to poor software architecture (Brown et al. 1998).

Different people have different points of view regarding where a system's boundary is. Some stakeholders such as business owners are often more interested in how the business runs than in how the software works. Developers often care more about the software than the business. For the stakeholders the system is the business and the environment is the world in which the business operates, with customers, suppliers, and competitors on the outside of the system. Resources such as the sales staff and customer service clerks are inside or part of the business. On the other hand, the developers may regard the sales staff and customer clerks as users, and therefore outside of the system.

Poorly defined boundaries lead to scope creep. Many stakeholders have “pet” problems they want a new system to resolve. Sales and marketing staff often load features onto a system in the hopes of capturing customer interest. Developers love to enhance or add features to even well-defined systems. Poorly defined or undefined boundaries exacerbate these problems. Without a clear definition of the system boundary, everyone tries to add features they deem even slightly necessary. But these extra features often don't add any value to the system. If anything, they make the system more complicated and less useful.

Imprecise and conflicting objectives early in the project often make it difficult to determine the boundary of a system. When a project is beginning, there may be insufficient information to identify what belongs to the system and what is part of its environment. The system may be large, or its purpose may not be clearly defined.

People believe that defining a boundary is unnecessary. Programmers often feel that analysis activities only get in the way of the real work (coding) and don't offer them any real value. This perception is especially true in the start-up world, where companies operate on a shoestring budget and their very livelihood depends heavily on the time it takes them to get their product to market. But this approach can quickly result in unnecessary and missing features, inadequate products, and excessive costs.

Therefore:

The VisibleBoundary limits and supports the SharedClearVision by:

In the early stages of development, the visible boundary may be fuzzy because the vision for the system may not be clear. Start by putting a stake in the ground and documenting the system boundary based on the information you have available to you. As you develop your use cases and learn more about the system, you can refine and sharpen the system boundary, that is, perform SpiralDevelopment (p. 52).

Examples

Wings Over the World: Context Diagrams

A context diagram is a useful tool for documenting the visible boundary between a system and its environment. It is a simple but information-rich diagram consisting of a circle and boxes connected by lines and arrows. The circle represents the system, and the boxes—called terminators—represent anything that is outside of the system. The lines running between the circle and the boxes represent the flow of data between the system and its terminators. In short, a context diagram shows what the system interacts with in its environment.

The context diagram, which can be drawn in UML as a deployment diagram, is a simple, effective tool for identifying potential actors and use cases, because it helps us focus on the things that interact with a system while ignoring the services that those things require.

In addition to simplicity, the benefit of using this kind of diagram is that it is based on information that is readily available early in the development cycle. With use cases, you must find actors and the services they need. On the other hand, with context diagrams, you need to find only the physical things that the system will talk to. You do not need to know what services it will require or deliver to the system.

The context diagram provides an excellent starting point for building the use case set. To find actors, we ask questions such as, “What are the different roles played by terminators such as customer, bank, and ticket wholesaler with respect to the system?” The diagram also identifies invalid actors. For example, Figure 4.4 shows that the system is the company. Since travel agents are part of the company, they are also part of the system. For this specific example, travel agents cannot be actors: any use case that portrays travel agents as actors will be inappropriate.

Figure 4.4. Context diagram for Wings Over the World

Just as important, context diagrams show what does not interact with the system. For example, the Wings Over the World system does not interact with independent hotels or car rental agencies. According to this diagram, actors and use cases for independent car rentals and hotels are outside of the system's scope.

The types of interactions that are outside of the system's scope can also be documented. For example, while this system does interact with customers and with the customer assistance system, it has no business getting involved in any direct interactions between the customer and customer assistance. A use case describing a scenario in which the customer phones customer assistance to complain about an airline or some other service is outside of the system's scope.

VisibleBoundary and UML Models, by Dan Rawsthorne

The context diagram is a lovely thing, and it can be drawn with standard UML. A good context diagram goes a long way to help “scoping” discussions, as well as provide the vocabulary necessary to develop a use case set.

I love drawing context diagrams and putting them up on the wall. Being constantly reminded of the environment the system lives in, the developers can stay focused on what's important, and realize what isn't. The context diagram is a natural counterpoint to the use case diagrams you have drawn for SpiralDevelopment (p. 52) and BreadthBeforeDepth (p. 48).

These diagrams make obvious the scope of the system's functionality from the inside and the outside. The context diagram shows the scope from the outside—what the boundaries of the scope are, while the use case diagrams show the functional scope from the inside—what functionality you consider important and will implement.

Group of Shakespearean players on stage

You have a SharedClearVision (p. 80) of the system's purpose and are establishing a VisibleBoundary (p. 86) that specifies who and what is outside of the system.

An actor is a person who plays a role, whether on stage, on TV or radio, or in movies. Some actors are so good that they make it hard to believe that they are not the role they are playing. Actors frequently get typecast into a role they play particularly well. For many people, it is difficult to distinguish Clint Eastwood from “Dirty Harry” or Sean Connery from “James Bond.” When actors play unexpected roles, such as when Clint Eastwood portrayed a caring, sensitive man in The Bridges of Madison County, viewers can come near to experiencing culture shock.

The craft of acting becomes stunningly clear when one actor plays several radically different roles in the same play or movie. In Stanley Kubrick's classic Cold War movie Dr. Strangelove (1964), Peter Sellers plays three distinct roles: the calm, rational Group Captain Mandrake, who is trying to prevent a nuclear holocaust; the ineffective, milquetoast President of the United States, Merkin Muffley; and the very mad scientist Dr. Strangelove. In acting, it's the role that we are interested in, not the person doing the acting. We don't follow Peter Sellers in Dr. Strangelove, we follow Mandrake, the President, or Strangelove. Each of these characters has his own traits and develops in different ways throughout the movie, and each role contributes to the development of the movie's plot.

Just like actors in a movie or on the stage, users may play many roles with respect to a system. If we do not understand all the roles a user plays, then we cannot understand the system.

To be useful, a system must satisfy its users' needs and protect the interests of its stakeholders. If the system is not to be deficient in its requirements, then we must find all the services its users need. A development organization can suffer a damaging loss of goodwill when it fails to provide the services that the users actually need instead of what they think they want.

Tying services to users may make the system so rigid that services cannot be reused. Different users may have overlapping sets of responsibilities. A single user can play many different roles with respect to the system. Many different users may actually share a single role with respect to the system. If we consider only the different users, then we may create a system with different interfaces for similar operations. Failure to discover overlapping responsibilities and separate them from the users will lead to bloated, rigid systems.

The narrow focus of subject matter experts can obscure all the services a user requires. Subject matter experts are quite vocal on the topics they care about, but they often have little interest in areas outside of their specific expertise. Unless we have a mechanism to probe and elicit from the subject matter experts all the services required by the user, the system will be deficient. (See the example “Centre A,” on p. 92.)

Focusing on users may bog us down with implementation details, rather than provide understanding of the services the user needs. Engineers love to solve challenging, detailed problems; that's why they became engineers in the first place. Focusing on users rather than the roles they play in the system runs the risk of prematurely introducing implementation details into our analysis (the “how” rather than the “what”). It is tempting to do so, because users are real. Engineers can grab on to them immediately and attack a big problem: How should the system communicate with the user? How should we lay out the user interface? What happens when the user asks for a nonexistent part number? It is not so easy to pull from thin air the services the system must offer the user.

Many people find it easier to comprehend concrete concepts rather than abstract ones. We hear this comment frequently: “If I can't point to it, then I don't want to know about it.” A person, machine, or even another piece of software is easy to point to and identify. The roles played by that same person, machine, or software are much more abstract and therefore more difficult for people to visualize. Furthermore, abstract concepts may sometimes mask fuzzy or imprecise thinking.

Time pressure and expediency encourage us to analyze only the users. Once the boundaries of the system have been identified, the users are relatively easy to find. After all, it is easy to identify users by name and job description. It is relatively simple to point to a box at the end of a cable that must communicate with your system. It takes more time and effort to find out that that box and that person play the same roles.

Therefore:

Analyze the system by focusing on the UserValuedTransactions (p. 95), or the set of services the system must offer the users. You should know at least who the users are because the SharedClearVision gives you a statement of the system's purpose and the VisibleBoundary gives you a glimpse of the scope of the system.

For each user, identify and list the services that the user requires from the system. Try to organize the services into cohesive sets, and then name those sets. Look carefully for users that have overlapping sets of services, and then collect those services into sets. Examine the sets of collected services to see if they are complete. Are any services missing? Once complete, these sets are the actors of the system and represent the roles that entities play with respect to the system.

Give each actor a clear, crisp noun or noun phrase name. If you cannot provide a good name for the actor, then the odds are that you have not identified an actor. Write a description for the actor specifying the services it requires from or offers to the system.

In the early development phases, it can be difficult to find the roles of the actors. Finding the roles of the users is often an emergent characteristic of creating the use cases. So don't get bogged down if you cannot find all of the roles right away, because they should naturally emerge as part of the SpiralDevelopment (p. 52) cycle.

Examples

Centre A: The Museum for Contemporary Asian Art

Centre A (www.centreA.org) is the Museum for Contemporary Asian Art in Vancouver, British Columbia, Canada. Its directors hope to create a museum that is more open and responsive to the needs of the community. One of the authors helped them write use cases to model the museum's mission and operation.

During the design of the Centre A use case set, our subject matter experts focused on the activities of the museum curator, specifically the curator's scholarly activities, such as the search for and acquisition of art for the museum. These experts were either artists or curators themselves. What we missed and had to recover from was that the curator also has the tedious, day-to-day job of simply running the museum. This role consists of the very mundane tasks of fighting the board of directors for funding, soliciting bids from contractors, authorizing purchase orders, and hiring and firing employees. In larger museums, some curators have only a scholarly role, while others have only a managerial role. Had we completely missed this management role, our system would have been grossly deficient. Yet this role of the curator as manager was largely hidden because it did not interest the subject matter experts (see BalancedTeam [p. 39]).

The Pharmacy Receptionist

In a pharmacy, there are three main actors: the Receptionist, the Pharmacy Technician, and the Pharmacist. Any one of these three actors may greet a Customer and take a prescription order. Either the Pharmacy Technician or the Pharmacist may fill the prescription, but only the Pharmacist can check and authorize the prescription. If we analyze only the users of the pharmacy system, then we risk overlooking the overlaps in responsibility between the Receptionist, Pharmacy Technician, and Pharmacist, and end up creating the model shown in Figures 4.5 and 4.6.

Figure 4.5. The Receive Customer use case when all users are treated as different actors

Figure 4.6. The actor list for the pharmacy system

By overlooking these shared job roles, we can lose the opportunity to simplify the system by capturing a common role. We need to understand and model the roles played by the system's users rather than model the users. In the worst case, we would design separate reception interfaces for the Receptionist, the Pharmacy Technician, and the Pharmacist without realizing that these three users play a common role and could share the same interface. We would be much better off by realizing this commonality, as shown by the model in Figures 4.7 and 4.8.

Figure 4.7. The Receive Customer use case, with the actor's role defined as Receptionist

Figure 4.8. Revised pharmacy system actor list

Bookies taking bets at the horse races. Warrenton, Virginia.

You have established a SharedClearVision (p. 80) of the project and have defined a ClearCastOfCharacters (p. 90) who need services from the system.

A few years ago one of the authors bumped into a colleague who was working for a start-up firm that was building a radio advertising distribution network. The idea was simple: Advertisers were using couriers to distribute tapes of their ads to radio stations, but even with overnight delivery, it could be two to three days before a new ad was actually playing over the radio. The colleague's company had built a continent-wide private network to distribute advertising spots to radio stations nearly instantaneously. Furthermore, with the company's proprietary protocols and compression hardware, they could guarantee quality of service to their clients.

It seemed like a license to print money. Offer a service that is cheaper, faster, and more reliable than what is currently available and the world will beat a path to your door. This was a case right out of Marketing 101. But the market never developed, eventually the company succumbed to the inevitable, and it was taken over.

A while later this story was mentioned to a radio DJ at a local station. “Doesn't surprise me that they failed,” he said. “Radio is a local media. Almost no one does national campaigns.”

A well-written set of use cases clearly and accurately describes the essential actions that a system provides. This information allows customers to preview a system before it is built and determine whether it offers the kind of services that they find valuable.

A set of use cases should capture the fundamental value-added services that users and stakeholders need from the system. An organization commissions the development of a system because that system will return some benefit. Use cases allow the organization's project team to inspect a system before it is built, so that they can verify that it is what they want, request changes, or decide that it doesn't meet their needs. Use cases should describe the kinds of things that users find valuable, so they can present the system in its best light. A system that does not deliver needed valuable services to its actors is deficient, can lose money, and will sully the reputation of the development organization.

It is relatively easy to identify low-level transactions, but it can be difficult to identify useful services. It is usually easier to describe the individual routine transactions that a system may provide than it is to discover what the user really wants to do with the system. Doing it the easy way often leads to “CRUD” (Create, Read, Update, and Delete) style use cases. It is not unusual to see use cases with names like Create Employee Record, Read Employee Record, or Delete Employee Record. While such use cases may be technically correct, they do not capture what is valuable to the user. Is creating an employee record important, or does the user really want to Hire Employee?

Use cases need to be relatively stable because they form “anchor points” for the rest of the product development process. Constant changes to use cases can ripple through the rest of the development process, creating havoc for the developers and significantly increasing the cost. To keep this cost low, we want to write each case at a level high enough to insulate it from inconsequential changes. Otherwise, the writers will constantly be updating their use cases every time someone changes some trivial detail. Worse, the readers will have trouble understanding the use cases, because their meaning will be constantly changing.

Readers want to see easily how the system will meet its goals. (See SharedClearVision.) Just as a picture is worth a thousand words, a use case is worth a thousand pages of system specifications. But even pictures can be hard to understand when they are too complex or abstract. Concise use cases that stick to the point are easier to read than long, flowery ones.

People tend to work at a level that is either too high or too low. People tend to use excessive detail when describing things they understand or find interesting. Conversely, they tend to gloss over details they don't understand or find boring. Use cases should be somewhere in the middle, containing enough information to describe system behavior adequately, without describing it in great detail (“what” versus “how”). If we write them at too high a level, then they are not useful to the system developers, because they do not describe the system in enough detail. However, if use cases contain too much detail, then it is difficult for non-programmers to understand the system from the 50,000-foot level. In the words of Ian Graham (1997), use cases should contain only necessary but essential information.

Therefore:

Ideally, a set of use cases should contain all of the information necessary to depict a system but no more. Each use case should describe some unique, essential service that is valuable to at least one user or stakeholder.

Use the ClearCastOfCharacters and SharedClearVision to identify those services that the system should provide. Define as many valuable services as you can for each actor in your cast of characters. Each service must help at least one actor reach a goal. Being unable to identify any service for an actor may indicate that the actor might not represent a valid system user; you may need to remove that actor from the cast. Conversely, if you identify a service that doesn't map to an actor in your cast, it may indicate that you have not identified all of the actors.

For each service that you identify, ask “What value does this service provide to the users or stakeholders?” Get rid of those services that fail to add value to the system. You don't want to waste valuable time writing use cases or implementing code for a feature that no one will use or cares about.

Users and stakeholders prefer to see the bottom line rather than an itemized list of CRUD-style services, so examine each service and determine whether each one stands by itself or is part of a larger, more valuable service. Fold those services that cannot stand by themselves into more comprehensive ones that address one key objective, and then eliminate duplicates. A client booking an airline reservation is interested in getting a good flight at a good price. The client doesn't care how many times the system updates its databases or files as the travel agent books a seat.

Write use cases around these goals. While you want to minimize the number of use cases in your collection, each use case should be a cohesive unit that describes one and only one key concept between an actor and the system, a CompleteSingleGoal (p. 118). Describe this collection in sufficient detail to adequately convey its purpose, yet at a high enough level so as to be insulated from simple changes.

This singleness of purpose does not prevent a use case from addressing more than one goal, as long as the use case is cohesive and achieves a unified purpose. For example, a high-level use case can reference several subordinate use cases in an EverUnfoldingStory (p. 102), but these use cases must work together to accomplish a common purpose.

Note: In BreadthBeforeDepth (p. 48), the actor names and the names of the user-valued transactions make up the original depth to which use cases should be taken before SpiralDevelopment (p. 52) is applied.

Examples

Wings Over the World and UserValuedTransactions

What are UserValuedTransactions for Wings Over the World? Where would our analyst look to find them? The vision statement is a great place to start, because it is supposed to state the objectives for the system. If the system is going to be successful, then its use cases need to support those objectives. The vision statement for Wings Over the World is repeated here as Figure 4.9.

Figure 4.9. The Wings Over the World vision statement

What are some of the valuable services the system may offer to support this vision? Some examples are:

• Book Trip

• Search for Flights

• Promote Vacations

• Create Trip Itinerary

• Update Trip Itinerary

• Delete Trip Itinerary

But are all of these services valuable? Book Trip, Search for Flights, and Promote Vacations are the kinds of things that successful travel agencies do to stay in business. But Create Trip Itinerary, Update Trip Itinerary, and Delete Trip Itinerary probably do not represent those goals a user would consider valuable. Each is a part of a larger service. Book Trip involves Create Trip Itinerary, Change Booking includes Update Trip Itinerary, and Cancel Booking involves Delete Trip Itinerary. These changes reduce the list to the following services.

• Book Trip

• Change Booking

• Cancel Booking

• Search for Flights

• Promote Vacations

Does this small list imply that a complex on-line travel Web site may have only ten or fifteen use cases? At the 50,000-foot level, the answer is yes: There will be only a few summary use cases. We can then unfold these use cases into their sea level use cases later. But what is most important is that we know the important and UserValuedTransactions.

Wings Over the World and Avoiding Form-Focus

Many use case writers make the mistake of creating a use case for each user interface form or external protocol message (Lilly 1999). The result is a set of many small use cases that add minuscule value to the primary actor. Following such a strategy could result in the set of use cases for booking an airline ticket shown in Figure 4.10.

Figure 4.10. A forms-based use case set

Each of these use cases describes the steps required to obtain a piece of information from some form and process it. Each use case may have a well-defined goal, but the goal is only a small step in booking an airline ticket for a customer. If we tried this approach for a larger system with many forms, we would end up with hundreds of small use cases, and we would lose the story context that is so valuable to our understanding the system.

It is easy to lose the context when writing these kinds of use cases, even in this small example. Are these three use cases all that is done to book a ticket? How do you know these are related to booking a ticket?

Furthermore, these use cases do not have goals that reflect the actor's point of view. This style of goal encourages writing use cases from the system's perspective rather than the actor's perspective. Note how each use case is named Get XXX, and would most likely describe how the system acquired information from the actor, rather than how the actor used the system to perform a useful task.

To the travel agent, the valuable transaction is not Get Payment Information, but Book Ticket. Get Customer Information, Get Flight Information, and Get Payment Information are really steps in the Book Airline Ticket use case. The goal of the travel agent is booking a ticket and making a sale, not gathering payment information, as Figure 4.11 shows.

Figure 4.11. Booking an airline ticket as a valuable transaction

If the steps Get Customer Information, Get Payment Information, and so on represent important and complex behavior, you can write them as lower level use cases (EverUnfoldingStory [p. 102]). Book Airline Ticket now gives a context into which these use cases fit, and makes it easier to comprehend the use case set.

The Cruddy Mortgage Origination System

A banking client was developing its next-generation mortgage origination system. This was the first project their team was tackling with use cases, and after their first cut they had come up with use cases such as these:

• Create Customer

• Update Customer

• Delete Customer

The Create Customer use case described the steps a loan officer took to add a customer to the customer database. The Update Customer use case described the steps to update customer information, and Delete Customer described the necessary steps to—well, you get the general idea. In short, the team was well on its way to building a CRUD-dy use case set: it would accurately describe behavior, but it would not be useful. For example, how is creating a customer a goal of measurable value to the loan officer? Or updating a customer? Or deleting a customer? The question here is “Why?” Why are you creating a customer? Why are you updating a customer? Why are you deleting a customer?

When asked about creating a customer, the loan officer replied, “Well, that's part of what I need to do when I open a new customer account. I have to create a customer.” Poof, the light bulb goes on in everyone's head: Creating a customer is part of a very valuable transaction called Open Customer Account. Now that's a goal that has measurable value to the loan officer.

Now what about that Update Customer use case? Still talking to the loan officer, we find out that updates are done in two situations: (1) making simple changes to the customer account such as changing an address or correcting misspellings; (2) adding documents that support the customer's request for a loan. So the two valuable transactions that result are Correct Customer Information and Acquire Supporting Documents.

Finally, why is a customer deleted from the database? “Well,” says the loan officer, “they're never quite really deleted. After we've approved or declined the loan, we archive the customer account.” So out of this comes Archive Customer Application.

Our three CRUD-dy use cases now become the much more valuable four:

• Open Customer Account

• Acquire Supporting Documents

• Correct Customer Account

• Archive Customer Account

Reduction gears, Pratt and Whitney Aircraft Corporation, East Hartford, Connecticut

You are organizing the UserValuedTransactions (p. 95) so that the context in which they sit, and their structure, are clear.

Imagine for a moment if all maps could be drawn at only one scale. If the uniform map scale was very fine, say, 1 centimeter equals 1 kilometer, then we could probably create a usable city street map. But then maps of the world would be totally unusable: a globe built to this scale would be some 40,000 centimeters in diameter! (That's about a quarter of a mile in diameter, for the metrically challenged.) If we changed from a fine scale to a very coarse scale, say, 1 centimeter equals 100 kilometers, then we could build a very serviceable globe, but we could never build a usable street map. This is why maps are drawn to a variety of different scales, such that the users of the map can easily use the map for the information they require: fine-scale street maps for finding an address in a city, and coarse-scale world maps for finding a city on the planet.

Different stakeholders view a system differently. If we limit our use cases to a particular viewpoint, we risk leaving much of our audience behind.

Each use case can have many readers and many uses, all requiring different levels of detail. Some use case readers are interested in system architectural issues and need a set of use cases to help them understand the big picture. Other readers care about business issues and need a set of use cases to help them understand the business layer, including details about system installation and testing. Still other readers will be involved in implementing the system and need the use cases to help them understand the complex interactions the system will allow. Each of these readers needs to see a different level of detail in one set of use cases. Accordingly, the use cases must contain enough information to satisfy all of them. If, for example, the use cases contain only high-level system descriptions, then the subject matter experts will not have the information that they need.

Use cases need to show how every function contributes value to the business. Every part of a system needs to directly add value to the business or support a process that does. Unnecessary functionality is expensive, adds extra cost to the system, and hinders performance. Accordingly, each use case needs to demonstrate this value to the readers, so that they can determine easily whether the functionality is required or not. It is much cheaper to eliminate unnecessary functionality early in the product development cycle, preferably in the requirements phase, because this pruning prevents the unnecessary allocation of precious resources during subsequent cycles.

It is, however, confusing to write at multiple levels. Writing at different levels requires an understanding of these levels. Not only must the writers know how the system should operate at different levels, but they must also comprehend the appropriate domain requirements and what the readers need to be effective at each level.

Writers need a principle to follow for organizing the requirements. Readers need an easy way to navigate through the use case set. Simply presenting the use cases en masse can overwhelm readers as they attempt to make sense out of the model. Good organization simplifies this task for the reader by allowing him or her to easily locate needed information. But good organization doesn't happen in a vacuum; it requires the writers to define comprehensive principles so that the readers can understand what they are trying to accomplish.

Therefore:

Just as maps are drawn at different scales to reveal or hide details, use cases can be written at different levels of abstraction. A good set of use cases contains several cohesive levels of related use cases that completely describe the system in different levels of abstraction, where each subordinate level closely resembles the level above it, albeit with greater detail.

Each individual use case captures a CompleteSingleGoal (p. 118) at whichever level it is placed. That goal may be found as a single step, the ActorIntentAccomplished (p. 156), in a higher level use case. The lower level use case shows the unfolding of that accomplishment.

A good way to describe unfolding use cases is to include several levels of use cases in your collection, where each level describes the system at a different level of detail.

In his book Writing Effective Use Cases, Alistair Cockburn (2001) suggests three levels of use cases.

Figure 4.12, adapted from Alistair Cockburn's book, illustrates the relationships among these levels. The higher level use cases provide the context for the lower level use cases. Or more simply, higher level use cases answer the question “Why is the actor doing this?” for lower level use cases. The lower level use cases answer the question “How is this going to happen?” for the higher level use cases.

Figure 4.12. Use case goal levels (Cockburn 2001)

Examples

Wings Over the World and Use Case Levels

The system developer's desire to have detailed specifications is a force driving us toward detailed use cases. But detailed specifications are long-winded and confusing to most people outside of the development community. If the use cases describe the system from only the programmers' level, they won't meet the needs of the stakeholders who also need them to understand the system.

This was one of the problems our consultant for Wings Over the World ran into. In our story, the analyst was told that the Wings Over the World development teams were “just tearing into the use cases, and had already written a thirty-page use case for booking a flight.” We don't know how you like to spend your time, but reading a thirty-page use case is not our idea of fun. Consider the use case fragment in Use Case 4.1 and Figure 4.13.

Figure 4.13. Book Flight

Use Case 4.1 Use Case Horror: The Thirty-page Book Flight Use Case

Book Flight

Level: User Goal

Main Success Scenario

1. This use case begins when a customer contacts the travel agency and requests a flight.

2. The customer proxy captures the customer's trip origin and destination.

3. The customer proxy looks up the airport codes for the origin and destination.

4. The customer proxy captures the preferred departure times for the customer.

5. The customer proxy captures the customer's preferred class of service.

6. The system requests from the airline proxy a list of the flights available that match the customer's preferences.

7. The system retrieves the customer's profile to get her preferred airline and frequent flyer number.

8. The system sorts the list of available flights first by the customer's airline preference and those that are closest to the customer's preferred departure times.

9. Etc., etc., for the next twenty-nine pages.

Would you want to read these steps for thirty pages? One solution to this problem is to maintain two parallel sets of use cases: one set written at the very detailed level required by the programmers, and a second set written at a much higher level of abstraction, much like a corporate report and its executive summary. Unfortunately, this approach has several problems. First, the use case set would remain relatively flat and without any context explaining why a given use case adds value to the business. Second, the scope of these use cases is often ambiguous, whether they are modeling the business or a supporting system. In our example, we have both business-level functions and system-level functions in one use case. To get around the problem of scope, many use case writers add a pseudo-actor they call the proxy. Finally, it is highly unlikely that the parallel use cases will remain parallel for very long.

A better approach (shown in Use Case 4.2) is to create a hierarchy of related use cases, organizing them as stories within stories that unfold as you need to discover more detail.

Use Case 4.2 Shortening Book Flight with EverUnfoldingStory

Book Flight

Level: User Goal

Main Success Scenario

1. This use case begins when a customer calls and requests a flight.

2. The customer describes her flight needs by specifying her origination, destination, travel dates, and preferred departure times.

3. The system looks up all flights that match the customer's travel preferences and presents the travel options to the customer.

4. The customer selects a flight.

5. The system builds a flight itinerary for the customer.

6. The system reserves the flight for the customer.

7. The customer provides a credit card number and charges the price of the flight against it.

8. The system issues the ticket to the customer.

When we need more details, we unfold the story and follow a more elaborate version of the use case set, as shown in Use Case 4.3 and Figure 4.14.

Figure 4.14. A more detailed version of Book Flight

Use Case 4.3 A Lower Level Use Case for Find Flight

Find Flight

Level: Subfunction

1. This use case begins when a customer contacts the travel agency and requests a flight.

2. The travel agent captures the customer's trip origin and destination.

3. The travel agent looks up the airport codes for the origin and destination.

4. The travel agent captures the preferred departure times for the customer.

5. The travel agent captures the customer's preferred class of service.

6. The travel agent confirms that the customer's preferences are correct.

7. The system requests from the airline reservation system a list of the flights available that match the customer's preferences, which is presented to the travel agent.

Someone who is interested only in understanding the steps involved in booking a flight and the possible alternatives (for example, flights unavailable, bad credit, restricted fares, and so on) can read the Find Flight use case and see if the right process is captured. They can unfold Find Flight and look at the lower level use cases if they wish to know the details of how we find a flight or build an itinerary.

The benefit of this approach is that it maintains the thread of the use case goals from the system vision to the lowest level use case. It helps us answer the question “Why is this use case here?” For example, why is there a Construct Itinerary use case?

Because it is an essential step for the Book Flight use case, which is a UserValuedTransaction (p. 95).

Many use case writers implement this solution by using the includes and extends relationships. In UML terms, when you reference a lower level use case from a higher level use case, the higher level use case includes the lower level one. That is, the steps from the lower level one could, in principle, be placed directly into the higher level one. Figure 4.15 shows how to structure a use case set with includes to show how lower level use cases are related to a higher level use case.

Figure 4.15. Use case horror: Distorted include association for EverUnfoldingStory

A lot of people like this approach because it provides a very satisfying drawing that clearly reveals a relationship between Book Flight and the other use cases. However, use case sets constructed in this manner can be confusing because of the myriad interpretations people have for includes and extends. We believe the application of includes and especially extends should be limited (see InterruptsAsExtensions [p. 182], CommonSubBehavior [p. 176], and PromotedAlternative [p. 190]).

Centre A: The Museum for Contemporary Asian Art

Centre A is an example of a use case set with the EverUnfoldingStory pattern. At the highest level is the use case Engage Art, shown in Figure 4.16.

Figure 4.16. An artistic rendering of Engage Art

For those of you who are mystified by an artist's hand-drawn use case, we present a more traditional UML diagram in Figure 4.17.

Figure 4.17. Engage Art

Use Case 4.4 Engage Diversity

Engage Diversity

The museum creates a forum in which the interests and cultures of everyone on the planet may be discussed.

Level: Summary

1. Audience bemoans the lack of diversity in society.

2. Curator develops a mission.

3. Curator conducts research for an event by creating forums to seek the input of the audience.

4. Curator produces event.

5. Curator hosts event.

6. Audience participates in the event.

The Engage Diversity use case (Use Case 4.4) provided the context for why a museum of art exists in our society. From this we could create a set of lower level use cases that described how the museum would accomplish this.

You will note in Figure 4.18 that Centre A took some liberties with the UML notation for use cases. Being artists, they were not too impressed with Ivar Jacobson's stick figures for actors. They were far more comfortable with the idea of a hat representing a role that someone plays. What is truly exciting about the Centre A model is that it has withstood nearly two years of debate and argument. The stakeholders have found it to be an excellent description of how a museum of art operates.

Figure 4.18. Centre A use case model

EverUnfoldingStory and UML Models, by Dan Rawsthorne

One way to deal with multiple levels is to have only one level of abstraction on each use case diagram. If you insist on drawing something like the diagram shown in Figure 4.15, then do the relations between abstraction levels with a trace relationship. The trace relationship is a predefined UML stereotype of a dependency (dashed arrow) that is used specifically to trace between different abstraction layers in a model. Figure 4.19 shows how Figure 4.15 can be revised to reduce the confusion caused by an includes relationship.

Figure 4.19. Book Flight

Of course, if your drawing tool will not allow you to use the trace relationship as shown, then you must do what you can. Just keep in mind that using an includes relationship may cause confusion—and at least you know what it should look like.

In the textual representation of the lower level use cases, you may want to show the traceability if the route through the EverUnfoldingStory is not enough. For example, the use case Reserve Flight Segments may look like Figure 4.20.

Figure 4.20. The Traceability of Reserve Flight Segments

This representation indicates that the Book Flight use case is being expanded, and that Reserve Flight Segments is part of the expansion. The Book Flight use case will simply have the reference to Reserve Flight Segments that one would expect by constructing the EverUnfoldingStory.

Properly organizing your use cases can return a lot of bang for your buck. An efficient, well-thought-out structure makes it much easier for everyone, readers and writers alike, to follow your use case. Organization requires effort, and everyone writing use cases needs to fully understand the system's purpose—what it does and does not do, who will use it, and what its boundaries are—so that they can accurately describe these facts to their audience. Furthermore, they should organize their use cases so that their audience can easily follow them and understand their value. While it requires some effort to write this way, structuring use cases is fairly straightforward and quickly pays for itself.

The first level of organization is as a set or collection. We want to organize its contents in a friendly, easy-to-use manner that allows the user to first see the system as a whole, then shift his or her focus to its individual pieces. A good way to do this is to describe the system as an EverUnfoldingStory (p. 102), which consists of several complete levels of use cases that present the system in increasing levels of detail. Each of these levels can stand alone and allow the reader to examine the system from a particular level of precision. Yet each subset expands into the next level of detail, allowing readers to “zoom in” on the parts they find interesting. This style allows some readers to examine the system from the 50,000-foot level and then focus on some of the low-level details of the system.

Creating an EverUnfoldingStory requires the writers to have a SharedClearVision (p. 80) of the system, so that they can clearly describe its purpose and tell their audience what the system will and will not accomplish. To successfully craft this story, the writers need to answer three questions clearly. We have identified three patterns to help them do this. First, we need to know who will use the system. We need a ClearCastOfCharacters (p. 90), describing everyone's role in the system. Second, we need to know what actions the users expect the system to do, actions that are UserValuedTransactions (p. 95). Last, we want to know where these actions are meaningful to the user; we want to know the system's VisibleBoundary (p. 86).

These latter three patterns are tightly coupled. If the system's boundary changes, then its cast of characters will grow or shrink as more actors move inside or outside of the boundary. The converse also holds: adding or removing actors from the cast will expand or decrease the system's scope and shift its boundary accordingly. Changing the cast of characters also affects the need for services. New actors require new services; removing actors usually reduces the number of services required.

The next chapter describes the characteristics of good use cases within the context of a set as the EverUnfoldingStory.