Wouldn't it be wonderful if there was one well-defined process for writing use cases? Then we could all learn the one universal methodology and know that everyone else clearly understands our ideas. Unfortunately, writing good use cases is highly personalized; everyone has his or her own style, and every organization has its own way of doing things, based on its culture and business needs. After all, it is these differences that give a business its competitive advantage. What is good for one group is not necessarily good for another.
While there is no one-size-fits-all process for creating use cases, we have captured common elements of good processes in the process patterns. It is important to note that these patterns do not constitute a process; that is, they don't follow one after the other. Rather, they make statements that are true about the process. For example, TwoTierReview (p. 64) describes inner reviews followed by an outer review. This pattern will be found in organizations using slightly different processes for writing their use cases.
An effective process creates use cases in a BreadthBeforeDepth (p. 48) manner, identifying potential use cases before describing them, adding details in a controlled manner, and achieving a SpiralDevelopment (p. 52) of the use case set. One of the biggest mistakes that people make while developing use cases is writing them sequentially. They start developing one use case, taking whatever time they need to write it, and don't start on the next one until the first one is finished. This approach has two drawbacks: (1) it is easy to get bogged down on difficult use cases at the expense of the remaining ones; and (2) facts uncovered during the development of later use cases often necessitate a rewrite of the earlier ones, wasting the original effort.
When it comes to use cases, different groups within a development organization should have the freedom to choose the format and level of detail that best meet their needs, instead of being required to use some “official” style. An effective process allows the writers to choose from MultipleForms (p. 58) and determine the appropriate level of detail. The group should use the same format for all the use cases in the same project to avoid confusion, but it is their decision to make, based on the project's complexity and the audience's need.
Reviews are a time-proven way of identifying errors and inadequacies; however, a traditional review process can often be ineffective for use cases because they can require a large, diverse group of reviewers with competing needs. To get around this problem, TwoTierReview describes how to stage reviews, in which those closest to the use cases review their correctness and completeness before turning them over to the larger group to review from a system standpoint.
One of the most difficult questions involving use case development is when to stop. The effective team knows when it is QuittingTime (p. 68). Rather than getting bogged down in long arguments about cosmetic issues, they allow a certain amount of WritersLicense (p. 73), recognizing that trying to enforce identical writing habits on everyone doesn't add economic value to the endeavor.
Blasting crew going into an ore vein with a horizontal drill. Mahoning pit, Hibbing, Minnesota.
BreadthBeforeDepth[*]
You are starting to write use cases with a SharedClearVision (p. 80) and a ClearCastOfCharacters (p. 90).
You will not make timely progress or create coherent use case sets if you waste energy writing detailed use cases sequentially.
It's hard to imagine building a house without an architect's sketch or drawing that shows us the big picture of how the completed house will look, and how it will relate to and influence its surroundings. The architect may also provide interior sketches to help us visualize the inside of the house. From these sketches an architect will begin to create the detailed plans for the house.
But homes have not always been designed in such a breadth-first manner. Back in the “good old days,” there was no big picture, and people living on the frontier literally built their houses one room at a time. Materials were scarce, and settlers didn't have the time to build large homes, so they just made do. Later, as they prospered and their families grew, they added more rooms onto the house, again one at a time. The results of this process are interesting: If you visit one of these homes today, you will notice unusual features such as exterior walls on the inside, or bedrooms you can only enter through other bedrooms. The tour guides at Abraham Lincoln's house in Springfield, Illinois, will tell you that the second floor “floats”; it is not anchored to any supporting walls because someone added it on later.
You can write better use cases if you have a good idea of what they will look like when you are finished. Unfortunately, you usually don't know that much about a system when you start. Developing use cases is a process in which you are continually learning and reevaluating your model. Fortunately, there are some things that you can do to help guide you along the way, and provide order to your process.
Requirements gathering is a process of discovery. It starts with a vague notion of the desired system, which makes it impossible to get the details correct the first time around. In most cases the people who commission the software system do not know exactly what they want and are unable to articulate their needs. The use case writing process is an iterative one in which you must define, analyze, and refine your underlying requirements in order to resolve conflicts and remove ambiguities from your model. The writing team will naturally write more suitable use cases once they better understand the system.
People are drawn into writing the details early. It is always difficult to begin a new project, and thinking about the whole, poorly understood system can be overwhelming. Trying to ramp up quickly is hard, and getting your head around a complex system is much akin to boiling the ocean. Developers often feel uncomfortable about spending the time necessary to comprehend a whole system, as they feel that they are wasting too much time, and should be producing something tangible instead. When people are not sure how to proceed, they have a tendency to dive into the nitty-gritty details and start specifying detailed requirements about the small parts of the system that they understand, even if those parts are not very important to the big picture. Unfortunately, project managers encourage this tendency because they measure progress based on concrete deliverables, and complete use cases fit the bill perfectly.
People lose energy or get bogged down in too much detail. A typical use case may have up to four general elements: actors and goals, main success scenario, failure conditions, and failure handling. It is easy to get drawn into pursuing too much detail when you are writing the narrative of the use case, as it is tempting to examine the alternatives. But whenever people follow a step with too many details—for example, its failure conditions and failure handling—they tend to lose their focus and energy describing all the possible extension conditions.
It is advantageous to get an overview early. If you start with an outline and then write just the essence of each use case, you give each stakeholder the opportunity to offer correction and insight early in the process. This approach also permits the work to be prioritized and split across multiple groups and releases, increasing parallelism and improving productivity.
The more detailed your early endeavors, the more you will have to change them as you learn more about the system. Most projects are short on time and energy, so continually changing the same use case is discouraging and stressful. The participants may start questioning their involvement and lose confidence in their use cases altogether.
Therefore:
Conserve your energy by developing an overview of your use cases first, then progressively add detail, working across a group of related use cases.
Start writing your use cases by outlining them before adding detail. Identify candidate use cases by associating a meaningful goal for each actor, defining a use case for every combination (UserValuedTransactions [p. 95]). Using the goal, derive a VerbPhraseName (p. 122) for each use case. Once you feel that you have defined a fairly complete set of use cases, work through your set, refining it, combining equivalent use cases and eliminating unnecessary ones (see MergeDroplets [p. 209]), RedistributeTheWealth [p. 204]), and CleanHouse [p. 213]). The resulting set of system goals provides a fundamental, shared understanding for the stakeholders and helps reduce the amount of refactoring required later on.
Once your overview is complete, develop the outlined use cases in an incremental manner, increasing the precision as you learn more about the system. Avoid the tendencies to complete an entire use case all at once or to write them one at a time. Instead, develop your use cases in a series of SpiralDevelopment (p. 52) cycles, incrementally adding detail and reviewing the effect the new detail has on the model, until you determine that it is QuittingTime (p. 68). Expand your use cases into ScenarioPlusFragments (p. 125) by describing the main success scenario of each use case, naming the various conditions that can occur, and then fleshing out some of the more important ones. Again, be ruthless about eliminating nonessential pieces from the collection. Add more detail to the fragments, creating a list of ExhaustiveAlternatives (p. 129) in the next cycle.
Templates are an essential use case development tool that provide organization and a common look and feel to the use cases. They are especially valuable when doing incremental development, because templates can serve as placeholders that allow the writers to organize their use cases while they are still missing large pieces. Simple or lower priority use cases don't always require the same amount of information as the more critical ones, so you can use MultipleForms (p. 58) to document each use case with an appropriate level of detail and precision.
Sometimes you do need to finish some use cases before others. In that case, take an incremental approach based on project priority. Identify the most important use cases, such as those that define the project, or those that need to be done first, based on business or technical issues. Prioritize these as you start writing, and work on them in groups for the aforementioned reasons. You may work on other use cases as well, but not at the expense of the most important ones.
BreadthBeforeDepth provides order to the use case writing process. The overview lets you see the big picture without getting bogged down in details. Working at a high level makes it easier to sketch in the system and its boundaries, as well as verify that your use cases provide complete coverage of all of the system's functionality. This high-level view also allows you to start project planning, and it enables you to prioritize your work and develop the most important use cases first—and do the less important ones later.
Working across a group of related use cases makes it easier to realign the use cases and eliminate the ones you determine to be unnecessary before expending much effort on them. Frederick Brooks's classic quote, “Be prepared to throw one away . . . because you will” (1995), is appropriate for writing use cases. Often a team learns more about a system's requirements as the project progresses, and the writers may have to dramatically alter or even throw away earlier work. The sooner you can identify unnecessary use cases, the better.
This pattern is closely related to the following one, SpiralDevelopment (p. 52). Therefore, we will defer offering an example until we have discussed it.
Spiral fire escape, St. Louis, Missouri
You are writing use cases in a BreadthBeforeDepth (p. 48) manner.
Developing use cases in a single pass is difficult and can make it expensive to incorporate new information into them. Even worse, it can delay the discovery of risk factors.
“Hindsight is 20/20,” “I wish I knew then what I know now,” and “If only I could turn the clock back” are all-too-common expressions that people use when they realize that they could have done better if they had had more information available to them earlier.
Writing use cases iteratively gives us a type of hindsight in that we can easily go back and scrap or redo them if we discover that they are not working out. We may lose some of our work, but much less than we would have lost had we simply written complete use cases one at a time. More important, we can identify and confront potential problems sooner using the iterative approach.
It can take a long time to understand a system's behavior. Learning is a linear process, and the more complicated the topic, the longer it takes to understand it. Students may like to “cram” before exams, but this technique only temporarily plants facts into their heads without giving them an understanding of the subject matter. Gaining a thorough understanding of a complex topic requires examining it piece by piece, using trial and error to learn its intricacies.
Delays are expensive. Requirements gathering is critical to a product's success, but it is only one part of the overall project. Many projects have tight deadlines, with many people depending on your use cases. So you need to finish your use cases as soon as possible so that others can ramp up to full speed.
The requirements are likely to change as a result of our examining them. Requirements are frequently volatile and likely to change as we learn more about them. There almost seems to be a Heisenberg Uncertainty Principle that applies to requirements: Analyzing a requirement tends to change the requirement. A requirement that once seemed cast in concrete crumbles upon further analysis. As you examine one requirement, you are likely to uncover information about others, and often discover that several requirements are wrong or missing. Another challenge is separating wants from needs. Things will eventually stabilize, but only after much analysis and rework.
The cost of requirements mistakes is high. An argument that is sometimes used to justify the waterfall software development life cycle is the downstream cost of fixing a requirements mistake. Such a mistake caught during the requirements analysis phase may cost only a nominal dollar to fix; the same mistake caught in the design phase, $2. The cost quickly escalates the later the mistake is discovered: implementation, $4; test, $20; deployment, $68 (Boehm 1981). No wonder there is a desire to get the requirements right the first time, up front.
If you dive in too quickly, you will overwhelm others. Use case development is usually a learning process for everyone involved. People require time to learn, and while you may understand the system, if you go too quickly, you may leave everyone else behind. It is important to finish your use cases in a timely manner, but it is more important that the whole organization has a chance to learn the system well, as they will be carrying most of the development load.
Therefore:
Develop use cases in an iterative, breadth-first manner, with each iteration progressively increasing the precision and accuracy of the use case set.
Working along BreadthBeforeDepth, pause when you have listed the actors and their goals, and work with that list for a while. Use the list to set up the project plan, estimate work, prioritize the use cases' value—even to help set up the development teams.
Continuing with BreadthBeforeDepth, choose a working subset of the use cases to expand, and pause again when you have a set of main success scenarios, to review the purpose of the system. Take the opportunity at this moment to review the use cases. See whether you need to MergeDroplets (p. 209) or CleanHouse (p. 213), or in any other way improve the structure. You may find yourself revising the list of actors and goals at this point.
You will probably find yourself revising your list of use cases one more time when you start working out the extension-handling behavior for your use cases. It often happens that new use cases turn up at this point. For example, when writing use cases for a simple ATM system, people usually don't think about what happens when there is a communications break between the ATM and its host computer. While writing down the details for handling that situation, it slowly occurs to people that when communications come back up, the ATM will have some specific work to do. Handling that system condition will force the team to create a new use case such as Reestablish Communications, which did not exist before.
SpiralDevelopment interacts with BreadthBeforeDepth. Imagine working to build all the use cases BreadthBeforeDepth, without any plan to revise the use cases along the way. Experience shows us, however, that as people add to the use case, they uncover new situations for which they have to write use cases, detect new similarities across use cases, and find new and better ways to structure the use case set. SpiralDevelopment advises the team that they will have to pause and regroup their work, and it indicates where to pause to review their work.
Key to the successful use of iterative development, of which SpiralDevelopment is an example, are knowing how to manage your energy in reviewing, and when it is time to stop. Use a TwoTierReview (p. 64), and stop as soon as you are sure that your use cases are good enough to meet your stakeholders' needs, so that you can avoid the law of diminishing returns. QuittingTime (p. 68) provides a set of criteria that you can use to determine that point.
The expression “Can't see the forest for the trees” describes one of the mistakes made by the use case team in this installment of the Wings Over the World story. Many use case teams divide the system up and assign portions to different use case writers. Each use case writer goes off and independently begins to write detailed use cases. Even though requirements may be vague, ambiguous, inconsistent, missing, or just plain wrong, the use case writers attempt to write very detailed use cases. Detail becomes a substitute for accuracy, and disagreements often break out between the writers as they try to resolve their differences. In this installment of the Wings Over the World story, a source of friction between Sitra and Ralph is that Sitra's work makes Ralph's work obsolete. Worse, Ralph has invested weeks of effort into writing his use case, and is not very happy about having to scrap that work.
Never underestimate the benefits of the big picture and incrementally developing and readjusting your use cases. When someone invests a lot of effort into creating a use case (or any other project artifact for that matter) he is reluctant to discard it, even when it really is unnecessary or incorrect. If Wings Over the World had followed the solution recommended by BreadthBeforeDepth, what would their work products look like?
First, they could start with something simple, such as an actor list that just enumerates the actors and the names of use cases they use. For example, a fragment of the Wings Over the World actor list may look something like Table 3.1.
Table 3.1. Sample Actor List for Wings Over the World
| Actor | Use Case |
|---|---|
| Agent | Reserve Flight Book Flight Cancel Flight Reservation Request Upgrade Open Passenger Profile Close Passenger Profile |
| Airline | Cancel Flight Discount Flight |
An actor list is not very precise, but it is accurate to the extent that we know the functional requirements for the system. The name for each of the use cases gives us some idea of what the goal of the use case is. Creating an actor list does not require a lot of effort, making it easier to change or drop proposed use cases. This list also helps us try to keep the goal level of each use case the same. It is easier to see at a glance if there are use cases that do not fit in with the others. In this example, Open Passenger Profile and Close Passenger Profile stand out because their goal level appears to be lower than the other candidate use cases. With little effort, these are quickly pruned out from the use case set or merged into other use cases.
Once the writers have finished the list, they may try to write simple, one-paragraph stories describing the main success scenario for the use case. These are often called briefs or high-level use cases. For example, see Use Cases 3.1 and 3.2.
Briefs allow us to refine the actor list and incrementally increase the precision of our use cases. These briefs tell us which actions the use case author believes are essential for reserving and booking flights. From them, we can tell that reserving a flight does not include paying for the flight or even selecting a seat; that is part of Book Flight. Briefs do not specify detailed steps, alternatives, preconditions, or post-conditions. Rather, their intention is to quickly cover the broad scope of the system, that is, its breadth, before we dive into the depths of the details. Briefs are easy to write, available for early review, and easy to fix. They allow you to detect and correct problems quickly, before problems gain a foothold and become ingrained in the system.
Once we have defined a broad system view, then we can expand a subset of the briefs and begin to fill in their details. We include step-by-step descriptions of the main success scenario, alternative courses of actions, preconditions, and post-conditions. It is important to note that we define only a subset of the briefs. Perhaps each use case writer takes one brief and simply enumerates the alternatives. Then, with this additional information added to the use case, the team may once again review the use case to determine what effect it may have on the other candidate use cases.
We call this technique Surface and Dive, where we take one or just a handful of use cases and dive down into the details once we have developed the broad scope of the system. Once at the bottom, we surface again to see what effect the detailed use cases have had on the rest of the use cases. We carefully adjust the model, select another subset of briefs, and dive down into the details of the use cases. Using this approach, even Sitra and Ralph may be able to come to a consensus.
Dictionaries and encyclopedias contain immense amounts of information, which their publishers are constantly revising. But the volumes are so large that the publishers don't want to start new editions from scratch and completely rewrite them every few years. Instead, they are written iteratively, reusing as much of the previous edition as possible, adding new words or articles as needed, and modifying or eliminating the obsolete entries. This method considerably simplifies the writing process, and greatly reduces the time to market. As an added bonus, the publisher can resell much of the same information every few years to the same customers.
Mrs. Ryan's dogs
You are writing use cases with a SharedClearVision (p. 80).
Different projects need different degrees of formality in their work, and various people have different preferences for the template. Requiring everyone to use the same use case template is counterproductive.
Taste in music is a highly personal thing. What is good for one person may not be acceptable for another. Some people like rock and roll, some like country, and never the twain shall meet. People will refuse to buy a particular album because they see it in the wrong section, or think it might be the wrong genre. When I was growing up, it was common for older people who would never buy a Beatles album (“It's not music”) to snap up Perry Como's or The Boston Pops' renditions of Beatles songs without a second thought. Music companies take advantage of these differences. They don't snub any type of popular music, but instead package each album to maximize sales in its particular market segment.
People and projects are different. Everyone is unique, and each person has his or her own way of looking at the world. Our personalities, experiences, and training shape our individual natures, and as a result, each of us sees things differently from other people. Similarly, each development organization has its own people, history, and culture that differentiate it from any other group.
Different projects have different needs. Projects may be large or small, simple or complex, and represent either new functionality or a remake of an existing system. For these projects, use cases might describe a business process, focus discussion about a future software system, describe functional system requirements, or document a system's design. You could develop your project locally, or be distributing the work over several teams in several geographical areas. Each of these factors affects the amount of formality you need in your use cases, and choosing the most appropriate form for your use cases must be done on a project-by-project basis.
You want to avoid getting caught up in unnecessary precision and rigor, costing your project a lot in expended time and energy. This risk needs to be balanced against the potential damage of missing key requirements. A format that is too lax will cause you to omit important details, but a format that is too rigid can create a lot of busywork that adds nothing to the qualities of the model.
Different teams want different amounts of formality. Different methods for documenting use cases exist to fulfill different needs. At one extreme, an organization may require very formal use cases that rigorously define all possible system behaviors, while at the other end of the spectrum, an organization may require very simple use cases. Any of these approaches can be correct, as long as they adequately describe what the developers and stakeholders need to know, with an appropriate level of detail.
Using a common form within an organization facilitates communication. A standard use case form or template makes it easier for people to know what information to put in their use cases as well as what information to expect from one. More important, because this form is usually well defined, it is easier to use and easier to understand the purpose of each of the use case's components.
Although templates are useful, some people have an insatiable urge to fill in all the boxes in one go. This depth-first approach can sap your energy and cause you to lose focus. Worse, it can waste a lot of time by forcing you to do unnecessary rework revising and refactoring your use cases as you learn more about the system. It is important to realize what needs to be completed at the desired level of precision.
Therefore:
Select the format based on the risks associated with the project and the preferences of the people involved.
Be open-minded when choosing a format for your use cases, and don't fall into the rut that all use cases should look alike. Use cases are only a tool for describing a system's behavior to your stakeholders and developers, and therefore need to meet only their needs for precision and content. Any more information is unnecessary.
Base your template selection on the purpose and level of risk associated with each use case. For critical use cases, write more formalized use cases containing a generous amount of information, and pay close attention to ExhaustiveAlternatives (p. 129) and PreciseAndReadable (p. 138). For less critical or better understood ones, be less formal and use less detail.
While it can be tempting to use different templates on the same project, it is not a good idea; multiple templates are way too hard for a team to wade through. Choose a standard template for any one project, and stay with it. The template will help the team handle the SpiralDevelopment (p. 52) of the use case set. A team of advanced practitioners may find it appropriate to write with differing amounts of formality and rigor for different use cases in the same set, but they should still use the same template to avoid confusion.
Sometimes, the name is all you need. I helped my team write use cases for a system that would distribute large “batch” jobs across a set of workstations and personal computers. During the course of the project, we identified approximately seventy use cases covering a wide range of system behavior. Because we had a strong understanding of the system from working on its predecessor, we annotated only the ten or so use cases that described the various ways the users would use the system. We left the rest blank (Use Case 3.3) because they described familiar behavior (for example, job monitoring, logging on to and off of the system, and so on). These sixty “textless” use cases were very valuable to us, as we used them to define the system servers and the boundaries between them. We could have annotated them, but our team was very small, and this effort would not have helped our already tight schedule. However, the annotated job flow use cases were very useful, because they significantly described interesting behavior that we would have to understand when we built the system. We referred to these use cases often, both with customers and in design meetings. Accordingly, we were able to build a successful system with a small team in a short period of time.
The key question is how much information does your audience need? Use cases 3.4 and 3.5, taken from Writing Effective Use Cases (Cockburn 2001), demonstrate different forms for the same use case. The first use case is appropriate when describing a high-level view of the process, or in those instances when the stakeholders already possess a good understanding of the feature.
Often your use cases require more detail or formality, as demonstrated by Use Case 3.5.
Children playing on a jungle gym
You have been writing use cases in a series of SpiralDevelopments (p. 52).
Many people may need to review the use cases. This is an expensive, time-consuming proposition.
Representative democracy is a system of government in which citizens elect people to represent them in a deliberative body. These representatives study the issues as they arise, and vote on them based on their understanding of the subject and their constituents' feelings. If a citizen has a concern about an issue, she can talk to her representative about it, potentially influencing the legislator's decision. The system isn't perfect, but it is certainly more efficient than having millions of people debating every issue or voting on each and every decision, big or small. While the representatives make the decisions, the voters have the final say. Voters can remove from office those representatives that they feel are ineffective or who have failed to represent them.
This system provides a good model for reviewing use cases, especially those intended for large, diverse groups of stakeholders. It allows every interested group to have its say as to the use case's contents, without overwhelming everyone, or requiring excessive time.
Reviews are necessary to verify and validate writing and content. Reviews are a good way to validate the correctness and completeness of a piece of work early in the development process. People tend to believe their work is better than it really is, often thinking that the quality of work is proportional to the effort spent on it. But inadequate, inaccurate work can distract the audience from a document's purpose; your stakeholders expect professionalism in business documents. It is harder for writers to catch their own mistakes because they are familiar with their work and tend to draw inferences from it that aren't necessarily there. People reading a document for the first time are more likely to notice errors because the errors distract them from understanding it.
The stakeholders have a vested interest in the use cases. Many different groups have a vested interest in a set of use cases and depend upon the use cases to help them do their work. It is in your best interest as a writer to consult with these groups early and often, to simplify your effort and minimize the amount of rework required to produce acceptable use cases that adequately address the stakeholders' issues.
It is expensive, tiring, and slow to involve everyone in the writing process. Teams with too many people tend to get in their own way, they are inefficient, and they require a lot of effort to coordinate. A SmallWritingTeam (p. 31) helps keep the process manageable and tends to cut down on feature creep.
If only a small writing team is doing the review, not all stakeholders' interests are incorporated. It is very difficult, if not impossible, for a small writing team of two or three people to represent the views of a large, diverse audience. A SmallWritingTeam without a ParticipatingAudience (p. 35) doesn't have the experience or the diverse knowledge base to understand or represent all of the stakeholders' views on a large project. It is likely that such teams will miss key parts of the system without this help.
Reviews can be expensive, tedious, and time-consuming. For a review to be effective, the participants need to invest a great deal of time and energy. The time spent on frequent or long reviews, with many people, quickly adds up to significant manpower. Therefore, we need to be judicious when conducting reviews, by scheduling them only when needed and requiring as few people as absolutely necessary. Also, while some people like reviewing development material, others despise it. You can allow all interested parties to attend, but keep the required attendance to a minimum.
Therefore:
Hold two types of review: The first by a smaller, internal team, possibly repeated many times; the second by the complete group, perhaps just once.
First, review the use cases internally to verify their readability, implementability, precision, and accuracy. These “inner” reviews can be informal desk reviews, formal meetings, or a combination of both. Any kind of review is appropriate as long as it allows the reviewers to catch errors and verify that your use cases are sufficient as far as they are concerned. One of the purposes of these initial reviews is to eliminate the “noise” caused by spelling, grammatical, formatting, and technical errors, which when left uncorrected are distracting.
You may need to hold several of these inner reviews when the system is large or overly complex. Because people tend to lose interest in detailed discussions outside of their own area of interest, consider holding separate group reviews for different functional areas when formally reviewing use cases aimed at a large, disparate customer base. That way, each group of stakeholders can review the use cases in depth from their particular point of view without distraction.
At the end of these inner reviews, the teams are asserting that it is QuittingTime (p. 68), and that the use cases are complete, correct, and as implementable as they need to be at this point. The use cases are then ready for the bigger group to check.
Hold at least one meeting with the complete group once the use cases pass internal muster, to review the system as a unified whole. Trust the first tier of reviews to validate the internal workings of the system, so that the second tier can focus on how the pieces fit together.
The definition of “complete group” varies by project. It should be all the people who review the requirements before development gets too far underway. In some cases it is just the development team; sometimes developers plus an executive; sometimes it is the business analysts and the lead programmers; sometimes it is users, executives, and the entire programming team. The purpose of the “outer” reviews is to determine the following.
Is this really the appropriate thing for the developers to spend time building? (business-value check)
Is this correct as a specification? (Are the business rules correct, and does it leave open the proper allowed variations in implementation? Does it lock down the important decisions? Does it identify the appropriate set of open issues that can be handled later?)
Can the developers really build it?
Many of the stakeholders are grumbling about the frequent reviews, and some are even refusing to participate. Is it necessary that every review be an all-hands effort? Of course not! SpiralDevelopment (p. 52) requires regular reassessments of the use cases to verify (1) that the use cases are a fair representation of the functional requirements and (2) that structurally the use cases exhibit the signs of quality advocated by the patterns listed in this book. The majority of stakeholders are only interested in reviewing the use cases to verify that the use cases protect their interests. Although all the stakeholders or their representatives want to participate in the project, they certainly don't want to spend long hours in formal and tedious use case meetings each week to review minor changes.
TwoTierReviews allow the writers to preview the use cases first, removing obvious errors and much of the “noise” that can be distracting and time-consuming in formal reviews. More important, they provide a “safety-valve” for the review process, ensuring that most of the stakeholders only see the use cases when they are hopefully complete, somewhat polished, and actually ready for review.
Once upon a time there was a programmer who was designing a new system for a large company. It was an important system that would alter the jobs of many people. The programmer wanted to make sure the interests of all the people affected by the system were protected, so soon after he finished a draft of the system vision, he cried out, “Review!” The moment he cried out, all the people came running to the conference room, because they knew that the last person to arrive would have to take minutes. For the next two hours, they reviewed the draft of the system, taking down action items. At the end of the meeting, all the people thanked the programmer for allowing them to verify that the vision addressed their interests.
The programmer incorporated all the action items into the second draft of the system vision and once again cried out, “Review!” Just as quickly as before, all the people came running into the conference room. For the next two hours, they all reviewed the updated draft. Some people grumbled this time that they had better things to do than sit in a review, but still most of the people thanked the programmer for allowing them to verify that the vision still addressed their interests.
The programmer incorporated all the action items from the second review into a third draft of the system vision and once again cried out, “Review!” As quickly as before, all the people came running into the conference room. For the next two hours, they all reviewed the updated draft. This time, most of the people grumbled that they had better things to do than sit in a review. They complained that they did not want to be called into another review unless there was something more than just document structure to look at.
The programmer incorporated all the action items from the third review into a fourth draft of the system vision and once again cried out, “Review!” But this time, no one came running to the conference room, not even the interns. “Review! Review!” cried the programmer. Still no one came. So the programmer decided to baseline the system vision anyway.
Unfortunately, this situation let an important feature fall through the cracks, and the company's CEO was embarrassed at a live demo when it was not there. The programmer ended up in the Call Center gulag because he had cried, “Review!” too often.
Day shift lining up before the time clocks to punch out. Bethlehem-Fairfield shipyards, Baltimore, Maryland
You have written a set of use cases in a BreadthBeforeDepth (p. 48) manner.
Developing a use case model beyond the needs of the stakeholders and developers wastes resources and delays the project.
Engineering history is full of stories of heavily overspecified and overdesigned systems. The military has often borne the brunt of these stories because they have a tendency to rigorously overspecify the requirements for any acquisition. We always hear about hammers and toilet seats procured by the military costing tens and sometimes even hundreds of times the price of their off-the-shelf cousins. While these incidents make entertaining news stories, they point to the real problem of overspecification.
We specify requirements to reduce the risk of creating the wrong system for the stakeholders, and many methodologies prescribe rigorous requirements specification procedures that must be closely followed. However, this rigorous approach to requirements specification does not take advantage of shared experience or common sense among the project participants. Consider buying a hammer: Most people simply walk into a hardware store and say, “I need a hammer,” trusting that the salesperson knows what they mean. If they want to be really precise, they might say, “I need a claw hammer.”
In contrast, military procedures may require the procurement officer to disregard common shared knowledge and say
I need a MIND—Manual Impact Nail Device. The MIND shall have an impact face between 15 and 20 millimeters in diameter and must be made from dropforged tungsten steel. The MIND shall also have an integrated NRU—Nail Recovery Unit—consisting of twin 30-millimeter carbon steel prongs, set apart in a V formation with a maximum gap spacing of 5 millimeters. Lastly, the MIND shall have a human-machine interface of oak or equivalent hardwood. . . .
It is easy to see how this practice delays simple acquisitions and escalates costs.
Good use cases are balanced, describing essential system behavior while providing only the necessary details about the interactions between a system and its users. They are complete enough so that their readers can easily understand what the system does, but they are not formal tomes that describe the system to the nth degree. Knowing when to quit writing use cases can be difficult, because deciding when to stop involves balancing some complex forces.
A paralyzing fear of overlooking important requirements encourages builders and stakeholders to prolong the requirements-gathering activity. Because it is much easier to fix requirements than it is to fix code, many developers will drag their heels and put off designing a system until they are absolutely sure that their requirements are correct. Some developers believe that the later a requirement error is found in the project, the greater the cost associated with rectifying the problem. Others fear the potential embarrassment and loss of stakeholder confidence if they overlook an important requirement.
Many technical professionals place an unwarranted high priority on model formality. Technical professionals are trained and indoctrinated in problem-solving techniques that require formal, precise descriptions. Formality is important from their point of view because it provides a “liberating form” for guiding and channeling the thought process, and it also minimizes ambiguity and omissions.
Ambiguity can destroy a project. Common engineering school dogma in the 1970s held that a slight miscalculation of less than one-tenth of one percent would have caused the Apollo spacecraft to miss the Moon completely, and send the astronauts into eternal orbit. Small details matter, and leaving the interpretation of vague requirements to the implementers' imagination can lead to missing functionality as well as some highly innovative features that take the product into unforeseen and unwanted areas. When writing use cases, stopping too soon is an easy way to introduce all kinds of ambiguity into a system.
Most people can work with a fair level of ambiguity. Many organizations possess “core competencies.” These attributes represent the shared knowledge and experience of the people within the organization that give the organization an advantage over its competitors. Core competencies help the organization reduce the risk associated with projects. For example, when a carpenter tells an apprentice to get a hammer and some nails, he probably does not have to explain the full details of what kind of hammer and what kind of nails to fetch. The context of the situation in which they are working and the shared background help the apprentice understand the specific needs of the situation.
Overspecification of requirements may convince stakeholders that the requirements are more accurate than they actually are. In high school science, many of us were taught the importance of experimental error. For example, we could not write in our laboratory notebooks that the mass of a specimen was 10.3482727 grams if our scale could only measure to a tenth of a gram of accuracy. We did not want to imply more precision in the result than we could actually measure. Stated another way, telling detailed lies does not make them any more accurate or truthful. Likewise, there is a tendency to assume that detailed requirements are more accurate (truthful) than less detailed requirements. Writing detailed requirements will hide the uncertainty associated with the requirements.
The cost of a mistake is quite small if it is caught early; often the cost of not moving ahead is exorbitant. Human beings make mistakes and have misunderstandings in the best of circumstances. The challenge is to discover quickly that a mistake has been made and exploit the knowledge gained from the mistake. Mistakes caught early in the project are less costly to fix. Delaying a project until all requirements are known can be dramatically more expensive.
Therefore:
Stop developing use cases once they are complete and satisfactorily meet audience needs.
You need to know what your goals for writing use cases are before you can determine if your use cases are complete. It is important to communicate clearly to all involved why you want to write use cases in the first place, as well as what problems and risks you need them to resolve.
To determine if your use cases are complete, ask the following questions:
Have you identified and documented all actors and goals?
Has the customer, or someone representing the customer, acknowledged that the use case set is complete, and that each use case is readable and correct?
Can your designers implement these use cases?
If the answer to any of these questions is no, then chances are you need to do more. Take advantage of the core competencies of the organization and the shared knowledge of the stakeholders to flesh out your use cases. Always keep in sight what the stakeholders need to see in the model. Once the stakeholders agree that the use cases adequately reflect their vision of the system, you are close to being finished, but it is important to satisfy all three questions.
Don't fuss too much about quality, and avoid excessive attention to adornments. There comes a point beyond which further development of the use case model will not yield any more understanding about the system. At this point you should exercise your WritersLicense (p. 73), “put your pencil down,” and move on.
You can always add more details later, as you learn more about the system. If moving on reveals ambiguities and uncertainties in the model, do not hesitate to pick up the pencil again and exploit the newfound knowledge. Be careful to consider the consequences to the entire system. Don't add the new details all at once to completion, but do it in an organized manner (that is, BreadthBeforeDepth), applying this information throughout the set of use cases where appropriate.
Ahmed and Ralph are arguing over the completeness of the use cases the team has written. Ahmed states that the use cases cannot be complete until all details are filled in. Ralph says that it is a waste of time and that they should just get on with it. Who is right?
“How do you know when you're done?” is one of the toughest questions to answer on a project. Many wonderful textbooks offer absolute answers to this question, but unless you have the financial resources of a federal government, you usually must push something out the door long before the completion criteria recommended by the textbooks. Like any real company, our fictitious Wings Over the World operates in a very competitive world and needs to deploy systems quickly.
QuittingTime is about balancing the risk of delaying the project with the risk of incomplete requirements. Software engineering textbooks often place a very high risk premium on incomplete requirements because they assume the development organization has little or no expertise in their problem domain, nor is there some level of trust between project members. But all of these factors usually exist in a company. The term “core competency” was coined in the 1990s to describe the advantage that knowledge and trust give to a company. Fast-moving, agile development methodologies such as XP take this to the extreme, where they take advantage of corporate knowledge for a high level of development agility. For example, XP requires a customer representative to be part of the development team to quickly resolve requirement shortcomings.
What the Wings Over the World story never makes clear is what the purpose of the use cases actually is, and who is going to use them. For example, if the intention is to outsource the development of the system, then the use cases require a great deal more rigor and completeness. The slow pace of communications between a client and its vendor would increase the risk in any of the ambiguities in the requirements. On the other hand, if the system is being developed in-house, the developers will have easy access to users and domain experts. If the developers take advantage of that close relationship, then they can tolerate a great deal more ambiguity.
Wings Over the World has decided to outsource a portion of the development of their new system. This decision implies that we need more rigor because of the higher potential for misunderstandings and the slower rate at which discrepancies are found in this type of situation. It is likely that the outsource vendor will have a template it uses for writing use cases. That template will be one part of a methodology used by a consulting company. But team members should be cautious that they do not fall into the trap of filling in every detail in the template for the sake of doing so.
The BreadthBeforeDepth (p. 48) approach facilitates an early QuittingTime, because it does not demand that every use case be written to a predefined level of detail. In fact, it may in some cases be acceptable to leave some use cases as briefs, when adding more detail does not add any new knowledge—the problem and solution are well known in the organization. This is an approach that relies on trust.
Bust of Shakespeare
You are conducting TwoTierReviews (p. 64) on your use cases, and are questioning whether it might be QuittingTime (p. 68).
Excessive emphasis on style issues unnecessarily impedes the effort of writing use cases.
Each year, film and television companies produce movies and TV programs based on true stories. Most of these productions take a creative license with the story to make it more appealing to a wider audience. For example, the film The Serpent and the Rainbow (1988) was based on a book by Wade Davis about a medical researcher looking for a new anesthetic in Haiti. When asked about the liberties the movie had taken with his story, Davis simply replied, “It's not exactly the story I wrote, but then I doubt that my story would have opened on 1700 screens.”
We should allow some freedom in our use case style to suit each unique system and audience.
We would like a consistent writing style, to simplify reading. A familiar style can be reassuring to readers when they are trying to understand something new. An inconsistent style, however, can confuse readers and make it difficult for them to find information; the mix of styles forces them to readjust to each use case. It can be especially frustrating to look for some information that appears in a different place in each use case.
It is costly and impractical to get everyone to write in exactly the same style. Writing is highly individualistic, and everyone has his or her own personal style. You could revise the use cases until they are similar, but this practice wastes time, energy, and money, and leads to sending the manuscript around and around and around. There comes a point when the law of diminishing returns takes effect, and the results aren't worth the effort. Style guides are useful, but they only solve part of the problem, because it is impossible for them to document every potential issue. A common style is “frosting on the cake,” but not worth substantial extra effort.
There is value in getting the use cases into development sooner. The sooner the developers have the use cases, the sooner they can start developing the product, and the sooner they can finish it. Every delay in moving use cases into development can cause project slippage, which costs money. It doesn't matter if the use case's style contains some minor variances; the developers can still use them.
We still need to meet the basic completion criteria of a use case being readable, logically correct, and detailed enough for the developers. The purpose of use cases is to provide information that accurately describes a system in an easy-to-read format. Use cases should correctly document enough knowledge so that the people depending upon them can easily find enough information to help them do their jobs, whether they are working with the big picture or implementing the low-level parts of the system.
Therefore:
Small differences in writing style are inevitable. Once a use case passes the tests for QuittingTime, the writer can claim “writer's license” on small stylistic differences.
Write each use case so that it passes the following tests.
It follows the organization's writing template and basic style.
It is logically correct.
It is readable to the end evaluators.
It is precise enough for the implementers to use.
Once the use cases meet these tests, allow each author to have final say on smaller stylistic matters. Small differences in writing style are up to each use case writer. Writers can claim “license” to make any changes they think appropriate and ignore other style changes they do not find worthwhile.
Style guides can be useful within a limited context, for a specific purpose, by describing a common “look and feel” for your use cases, and informing the writers about standard use case properties. Just be sure to treat such manuals as guides, not as a set of iron-clad rules. They should be flexible enough to promote individual creativity and not hinder the exchange of information.
Chief Architect Ahmed is suggesting a rigid style manual that specifies the rules for writing use case descriptions. While his intentions are good, they defeat the utility of a use case. Use cases are meaningful to the project participants because they are semiformal artifacts. They have enough structure so that the readers can ferret out the inconsistencies and gross ambiguities in the requirements, but not at the expense of making them unreadable to someone who is not expertly trained in the methodology.
All project participants have gone through a basic one-day use case course, so they do know what a use case is about. But can you imagine trying to get a travel agent or marketing manager to understand pseudocode? For requirements to be useful, they must be well understood by those who must review those requirements.
Use case writers frequently abuse templates. Templates represent a good checklist of items that may be included in the final use case, not a prescription for everything that must be in the use case. One of our personal peeves is with the preconditions section of a use case. Easily 90 percent of the use case preconditions that we have seen state something to the effect of “User is logged on.” While this may be valid, does it really add value to the use case? Writers should determine what helps the audience understand the use case, and what words or phrases contribute nothing.
Following the right development process is critical to writing quality use cases. This process doesn't have to be elegant or “high powered,” but it does need to cover all the bases. For developing use cases, good process means balancing discovery versus writing and content versus need. Although it would be nice to have one, there is no one-size-fits-all process for creating quality use cases. Writing use cases is highly personalized; everyone has his or her own style, and every organization has its own way of doing things, based on its culture and business needs. Yet, while there are multiple ways of writing quality use cases, the better processes share several common elements. The process patterns presented in this chapter describe the characteristics of effective use case development, and are intended to help you create your own process.
These patterns are closely related to each other, each describing a different aspect of use case development. As a result, they tend to work together rather than conflict with each other, and we don't really see any trade-offs among them. MultipleForms (p. 58) recommends formatting use cases in a style that is appropriate to the project and the audience's need, instead of using a companywide standard form. Everyone writing use cases for a particular project should use the same template, but choosing which one should be the team's own decision. BreadthBeforeDepth (p. 48) and SpiralDevelopments (p. 52) are very tightly coupled, and form an efficient basis for developing use cases. Working across a set keeps the set balanced, and keeps you aware of the relationships among its various members. If you determine that two use cases really address the same issue, or that some are unnecessary, you can react sooner in the writing cycle, minimizing the amount of unnecessary work. But this method by itself can be overwhelming, unless you do it in reasonably sized chunks, developing the use cases incrementally in a series of cyclic expansions. Writing use cases is a discovery process in which you often learn things affecting several use cases while researching others. Breadth-first development is an efficient way to keep from getting ahead of yourself on any particular use case, and avoid revising it continually as you learn more about the system.
This iterative approach also allows an organization to determine when its use cases are “good enough” for its purposes, and stop writing them before reaching the point of diminishing returns. Yet, to stop with any degree of confidence, writers need to have some well-defined criteria. The pattern QuittingTime (p. 68) says you can quit writing use cases when (1) you believe that you have identified and documented all actors and goals, (2) the customer has approved the use cases, and (3) you believe that the developers can implement the system from these use cases. TwoTierReview (p. 64) prescribes an efficient review process that helps verify that the use case collection is correct and complete, and it facilitates ParticipatingAudience (p. 35). WritersLicense (p. 73) states that small stylistic details are not that important, and that you can stop writing once you have addressed all of the system issues, even if some stylistic issues remain.
Process is only half the battle of writing high-quality use cases. Effective use cases are organized into a structure that clearly identifies certain key features of the system and allows readers of various backgrounds to use the various pieces easily. This structure is the subject of the next few chapters.
[*] This pattern was influenced by Rick Ratliff's Breadth First pattern from the OOPSLA 98 Use Case Patterns workshop.