Writing Effective Use Cases By Alistair Cockburn.pdf

Preface More and more people are writing use cases, for behavioral requirements, for ware systems or to describe business processes.. I include examples of good and bad use cases, plausi

What Is a Use Case (More or Less)?

A use case defines a contract among system stakeholders regarding its behavior, detailing how the system responds to requests from a primary actor aiming to achieve a specific goal It encompasses various scenarios that illustrate the system's reactions under different conditions, ensuring the interests of all stakeholders are safeguarded By compiling these diverse scenarios, the use case provides a comprehensive understanding of the system's functionality and interactions.

Use cases primarily exist in text format, but they can also be represented through flow charts, sequence charts, Petri nets, or programming languages Typically, they facilitate communication between individuals, often those without specialized training, making simple text the most effective option.

The use case, as a form of writing, can stimulate discussion within a team about an upcoming system The team might or might not document the actual requirements

Chapter 1 introduces the concept of use cases, highlighting their application in documenting final designs across various scales, from entire companies to specific software applications Despite the varying levels of rigor and technical detail employed by different teams, the fundamental principles of effective writing remain consistent across all scenarios.

When documenting an organization's business processes, the system under discussion (SuD) refers to the organization itself, encompassing stakeholders such as shareholders, customers, vendors, and regulatory agencies Key actors in this context include the company's customers and potentially their suppliers.

Use cases capture the behavioral requirements of software, with the System Under Development (SuD) representing the computer program itself Key stakeholders include the end-users, the owning company, regulatory agencies, and other software systems The primary actor in this context is the user interacting with the program via a computer screen or another system.

A well-crafted use case is clear and concise, featuring simple action steps that describe how an actor achieves a result or communicates with another actor Reading a use case should take just a few minutes, making it accessible and easy to understand.

Writing an effective use case can be challenging as it requires the writer to grasp three essential concepts that influence each sentence and the overall structure This complexity becomes evident when attempting to draft your initial use case, highlighting the importance of clearly understanding these three foundational ideas.

◆ Scope: What is really the system under discussion?

◆ Primary actor: Who has the goal?

◆ Level: How high- or low-level is that goal?

Several examples of use cases follow The parts of a use case are described in the next chapter For now, remember these summary deﬁnitions:

◆ Actor: anyone or anything with behavior.

◆ Stakeholder: someone or something with a vested interest in the behavior of the system under discussion (SuD).

◆ Primary actor: the stakeholder who or which initiates an interaction with the SuD to achieve a goal.

◆ Use case: a contract for the behavior of the SuD.

◆ Scope: identiﬁes the system that we are discussing.

◆ Preconditions and guarantees: what must be true before and after the use case runs.

What Is a Use Case (More or Less)? 3

◆ Main success scenario: a case in which nothing goes wrong.

◆ Extensions: what can happen differently during that scenario.

In the extensions, the numbers correspond to specific step numbers in the primary success scenario, indicating various conditions that may arise For example, steps 4a and 4b highlight two distinct situations that can occur at step 4.

◆ When a use case references another use case, the referenced use case is underlined.

The first use case involves a user aiming to purchase stocks online in a single session, marked at the user-goal level with a sea-level symbol In contrast, the second use case details an individual seeking compensation for a car accident, a process that extends beyond one sitting, indicated at the summary level with an above-sea-level symbol Further details about these symbols can be found in Chapter 5 and summarized on the front cover.

The first use case illustrates an individual's engagement with a web-connected program known as "PAF" on a workstation, represented by a black-box symbol to denote the computer system involved The second use case focuses on the interaction between a person and a company, symbolized by a building icon While the use of these symbols is optional, clearly labeling the scope and level of interaction is essential for clarity.

Here are Use Cases 1 and 2.

Use Case 1 Buy Stocks over the Web

Scope: Personal Advisors / Finance package (PAF)

Purchaser—wants to buy stocks and get them added to the PAF portfolio automatically.

Stock agency—wants full purchase information

Precondition: User already has PAF open.

Minimal Guarantee: Sufﬁcient logging information will exist so that PAF can detect that something went wrong and ask the user to provide details.

Success Guarantee: Remote web site has acknowledged the purchase; the logs and the user's portfolio are updated.

1 Purchaser selects to buy stocks over the web.

2 PAF gets name of web site to use (E*Trade, Schwab, etc.) from user.

3 PAF opens web connection to the site, retaining control.

4 Purchaser browses and buys stock from the web site.

5 PAF intercepts responses from the web site and updates the purchaser’s portfolio.

6 PAF shows the user the new portfolio standing.

2a Purchaser wants a web site PAF does not support:

2a1 System gets new suggestion from purchaser, with option to cancel use case. 3a Web failure of any sort during setup:

3a1 System reports failure to purchaser with advice, backs up to previous step. 3a2 Purchaser either backs out of this use case or tries again.

4a Computer crashes or is switched off during purchase transaction:

4a1 (What do we do here?)

4b Web site does not acknowledge purchase, but puts it on delay:

4b1 PAF logs the delay, sets a timer to ask the purchaser about the outcome. 5a Web site does not return the needed information from the purchase:

5a1 PAF logs the lack of information, has the purchaser update questioned purchase.

What Is a Use Case (More or Less)? 5

Use Case 2 Get Paid for Car Accident

Claimant—to get paid the most possible.

MyInsCo—to pay the smallest appropriate amount.

Department of Insurance—to see that all guidelines are followed.

Minimal Guarantees: MyInsCo logs the claim and all activities.

Success Guarantees: Claimant and MyInsCo agree on amount to be paid; claimant gets paid that.

1 Claimant submits claim with substantiating data.

2 Insurance company veriﬁes claimant owns a valid policy.

3 Insurance company assigns agent to examine case.

4 Insurance company veriﬁes all details are within policy guidelines.

5 Insurance company pays claimant and closes ﬁle.

1a1 Insurance company requests missing information.

2a Claimant does not own a valid policy:

2a1 Insurance company denies claim, notiﬁes claimant, records all this, terminates proceedings.

3a No agents are available at this time.

3a1 (What does the insurance company do here?)

4a Accident violates basic policy guidelines:

4a1 Insurance company denies claim, notiﬁes claimant, records all this, terminates proceedings.

4b Accident violates some minor policy guidelines:

4b1 Insurance company begins negotiation with claimant as to amount of payment to be made.

This book features real-world use cases from live projects, presented without embellishment to highlight practical effectiveness rather than theoretical appeal Recognizing that time constraints often prevent the creation of formal and polished use cases, the focus is on providing sufficient examples that demonstrate what truly works in practice.

I show these real samples because you rarely will be able to generate perfect use cases yourself, despite my coaching Even I can’t write perfect use cases most of the time.

Use Case 3, authored by Torfinn Aas from the Central Bank of Norway, demonstrates the adaptability of the form while maintaining its value By incorporating additional business context, the writer effectively illustrates the computer application's functionality throughout a typical workday This approach not only enhances clarity but also eliminates the need for a separate document detailing the business process, ensuring that all involved parties find the information both informative and easy to understand.

Use Case 3 Register Arrival of a Box

Scope: Nightime Receiving Registry Software

1 RA receives and opens box (box ID, bags with bag IDs) from Transport Company (TC)

2 RA validates box ID with TC registered IDs.

3 RA maybe signs paper form for delivery person.

4 RA registers box’s arrival into system, which stores:

5 RA removes bags from box, puts on cart, takes to RO.

2a Box ID does not match transport company ID.

4a Fire alarm goes off and interrupts registration.

Leave money on desk and wait for computer to come back up.

4' With and without Person ID.

4'' With and without estimated value.

5' RA leaves bags in box.

Your Use Case Is Not My Use Case 7

Your Use Case Is Not My Use Case

Use cases are a form of writing that can be put to work in different situations, including the following:

◆ To describe a business's work process.

◆ To focus discussion about upcoming software system requirements, but not to be the requirements description.

◆ To be the functional requirements for a system.

◆ To document the design of the system

◆ To be written in a small, close-knit group, or in a large or distributed group

Each situation calls for a slightly different writing style Here are the major subforms of use cases, driven by their purpose.

In a close-knit group setting, gathering requirements often leads to the creation of casual use cases, as opposed to the fully dressed use cases typically produced by larger, geographically dispersed teams This casual approach allows for quicker documentation by bypassing the formal use case template For instance, while Use Cases 1 through 3 adhere to a comprehensive format, Use Case 4 exemplifies the more streamlined casual form, highlighting the efficiency of this method.

Business process professionals create business use cases to outline their operations, while hardware and software development teams focus on system use cases to capture their specific requirements Additionally, design teams may draft system use cases to document their design processes or to decompose requirements for smaller subsystems.

When writing, the author must determine the appropriate level of detail to convey, choosing between a multi-sitting or summary goal, a single-sitting or user goal, or a specific subfunction of a user goal Clearly communicating this choice is crucial, leading my students to develop two distinct gradients for description: one based on elevation (above sea level, at sea level, underwater) and another based on color (white, blue, indigo).

When creating requirements for a new system, writers typically produce black-box use cases that focus on user interactions without delving into the system's inner workings In contrast, business process designers often develop white-box use cases to illustrate the internal processes of an organization Additionally, technical development teams may also create white-box use cases to document both the operational context of the new system they are designing and the functionalities of the system they have just developed.

The versatility of the use case writing form is impressive, yet it can lead to confusion among users When collaborating, team members may disagree on writing approaches due to differing purposes for their use cases Additionally, over time, various combinations of these characteristics may arise, further complicating the writing process.

Throughout this book, we will explore various use cases, acknowledging the complexities and variations inherent in each While it may be challenging to establish a universal framework for discussing these cases, I will outline the key issues here and allow the examples to illustrate the concepts in detail.

You may want to test yourself on the use cases in this chapter Use Cases 1, 3, and

Five use cases were developed to outline system requirements, characterized as fully dressed, black-box types at the user-goal level Use Case 4 mirrors this format but is presented in a more casual manner In contrast, Use Case 2 serves as a context-setting use case for business process documentation, also fully dressed and black-box, but presented at a summary level.

The largest difference between use case formats is how “dressed up” they are. Consider these quite different situations:

A dedicated team is developing software for a critical project and recognizes the value of thoroughness, opting for a more detailed use case template To minimize ambiguity, they ensure that the writing team maintains a consistent style Additionally, they implement stricter review processes to closely examine use cases for any omissions or unclear elements With a low tolerance for errors, they also aim to reduce variations in use case writing among team members.

A small team of three to five individuals is developing a system where the most significant risk is merely a loss of comfort, easily resolved with a phone call They view formal processes as inefficient and opt for a simpler approach that allows for greater flexibility in writing styles and fewer, more lenient reviews Errors in their documentation are expected to be identified through team discussions and user interactions, enabling them to embrace a more relaxed writing style and accommodate variations among team members.

Making choices on a project-by-project basis is essential, as there is no one-size-fits-all solution This crucial lesson, learned over the past five years, emphasizes the importance of tailoring methodologies to specific project needs, despite the ongoing challenge of translating this concept into actionable advice.

Focusing excessively on precision and rigor can lead to significant time and energy losses in your project As Jim Sawyer noted, it's crucial that templates remain flexible and do not become overly formal, as this can cause confusion and hinder the design process.

I say strip the little buggers naked and start telling stories and scrawling on napkins.”

One use case template is insufficient; at least two are necessary: a casual template for low-ceremony projects and a fully dressed template for higher-ceremony projects Each project can adapt one of these two forms to fit its specific needs Below, the same use cases are presented in both styles.

Use Case 4 Buy Something (Casual Version)

The process begins when the Requestor submits a request to the Approver, who verifies budget availability and the pricing of the goods After completing the necessary checks, the Approver forwards the request to the Buyer The Buyer then assesses storage inventory and identifies the most suitable vendor for the goods Following this, the Authorizer confirms the Approver’s signature, allowing the Buyer to finalize the order request and initiate a Purchase Order (PO) with the selected vendor.

The vendor delivers goods to the Receiving department, which issues a receipt for the delivery; however, this process is not included in the current system design The Receiver then registers the delivery and forwards the goods to the Requestor, who subsequently marks the request as delivered.

At any time prior to receiving goods, the Requestor can change or cancel the request Canceling it removes it from any active processing (deletes it from system?)

Reducing the price leaves it intact in processing Raising the price sends it back to the Approver.

Use Case 5 Buy Something (Fully Dressed Version)

Goal in Context: Requestor buys something through the system, gets it Does not include paying for it

Scope: Business—the overall purchasing mechanism, electronic and nonelectronic, as seen by the people in the company

Requestor: Wants what he/she ordered, easy way to do that.

Company: Wants to control spending but allow needed purchases.

Vendor: Wants to get paid for any goods delivered.

Minimal Guarantees: Every order sent out has been approved by a valid authorizer

Order was tracked so that company can be billed only for valid goods received.

Success Guarantees: Requestor has goods, correct budget ready to be debited.

Trigger: Requestor decides to buy something.

2 Approver: check money in budget, check price of goods, complete request for submission.

3 Buyer: check contents of storage, ﬁnd best vendor for goods.

5 Buyer: complete request for ordering, initiate PO with Vendor.

6 Vendor: deliver goods to Receiving, get receipt for delivery (out of scope of system under design).

7 Receiver: register delivery; send goods to Requestor.

1a Requestor does not know vendor or price: Leave those parts blank and continue.

1b At any time prior to receiving goods, Requestor can change or cancel request:

Canceling it removes it from active processing (Delete from system?).

Reducing price leaves it intact in processing.

Raising price sends it back to Approver.

2a Approver does not know vendor or price: Leave blank and let Buyer ﬁll in or callback.

2b Approver is not Requestor's manager: Still OK as long as Approver signs.

2c Approver declines: Send back to Requestor for change or deletion.

3a Buyer ﬁnds goods in storage: Send those up, reduce request by that amount, and carry on.

3b Buyer ﬁlls in Vendor and price, which were missing: Request gets resent to

4a Authorizer declines Approver: Send back to Requestor and remove from active processing (What does this mean?)

5a Request involves multiple Vendors: Buyer generates multiple POs.

5b Buyer merges multiple requests: Same process, but mark PO with the requests being merged.

6a Vendor does not deliver on time: System does alert of non-delivery.

7a Partial delivery: Receiver marks partial delivery on PO and continues.

7b Partial delivery of multiple-request PO: Receiver assigns quantities to requests and continues.

8a Goods are incorrect or improper quality: Requestor refuses delivered goods

8b Requestor has quit the company: Buyer checks with Requestor's manager: either reassign Requestor or return goods and cancel request.

Technology and Data Variations List: None.

Channel to Primary Actor: Internet browser, mail system, or equivalent

Channels to Secondary Actors: Fax, phone, car

When is a canceled request deleted from the system?

What authorization is needed to cancel a request?

Who can alter a request's contents?

What change history must be maintained on requests?

What happens when Requestor refuses delivered goods?

How does a requisition work differently from an order?

How does ordering reference and make use of the internal storage?

I hope it is clear that simply saying, “We write use cases on this project” does not say very much, and that any recommendation or process deﬁnition that simply says,

Writing use cases requires careful consideration, as what is applicable in one project may not be suitable for another It's essential to clarify whether fully dressed or casual use cases are being utilized, specify which template components and formats are mandatory, and define the acceptable level of variation among different writers.

Requirements and Use Cases

If you are writing use cases as requirements, keep two things in mind:

◆ They really are requirements You shouldn’t have to convert them into some other form of behavioral requirements Properly written, they accurately detail what the system must do

While these requirements are crucial, they represent only a portion—approximately one-third—of the total necessary information They do not encompass external interfaces, data formats, business rules, or complex formulas, highlighting the need for a more comprehensive collection of requirements.

Organizations gather requirements to meet their specific needs, and there are established standards for documenting these requirements Among these standards, use cases represent just one component of the overall requirements documentation.

I find the following requirements outline particularly useful, having adapted it from a comprehensive template by Suzanne Robertson and the Atlantic Systems Guild, as featured in their book "Managing Requirements" (Robertson and Robertson, 1999) While their original template is thorough, I have streamlined it to a more manageable form that serves as a guideline for my projects Even this condensed version can be extensive for many projects, prompting me to further refine it as necessary Regardless of its length, the outline raises thought-provoking questions that are often overlooked.

“What is the human backup to system failure?” and “What political considerations drive any of the requirements?”

While it is not the role of this book to standardize your requirements deliverable,

Many individuals are unfamiliar with a requirements outline, so I’m sharing one for your review This outline aims to highlight the role of use cases within the broader requirements framework, emphasizing that while use cases are essential, they only capture the behavioral aspects and necessary functions, rather than encompassing all requirements.

1a What is the overall scope and goal?

1c What is in scope, what is out of scope?

2a The primary actors and their general goals

2b The business use cases (operations concepts)

4a What technology requirements are there for this system?

4b What systems will this system interface with, with what requirements?

Q1 Who are the project participants?

Q2 What values will be reﬂected (simple, soon, fast, or ﬂexible)?

Q3 What feedback or project visibility do the users and sponsors want? Q4 What can we buy, what must we build, what is our competition?

Q5 What other process requirements are there (testing, installation, etc.)? Q6 What dependencies does the project operate under?

Chapter 6 Human Backup, Legal, Political, Organizational Issues

Q1 What is the human backup to system operation?

Q2 What legal and what political requirements are there?

Q3 What are the human consequences of completing this system?

Q4 What are the training requirements?

Q5 What assumptions, dependencies are there on the human environment?

Use cases, detailed in Chapter 3 of the requirements, represent the complete set of behavioral requirements but do not encompass all requirements Other essential components, such as business rules, glossary terms, performance targets, and process requirements, fall outside the behavioral category and necessitate their own dedicated chapters.

Use Cases as Project-Linking Structure

Use cases serve as a vital framework that links various details within requirements, facilitating the integration of user profile information, business rules, and data format specifications They enhance coherence by connecting disparate information across the requirements, ensuring a comprehensive understanding of the project's needs.

Use cases play a crucial role in structuring project planning by organizing essential information like release dates, team assignments, priorities, and development status Additionally, they assist the design team in monitoring specific outcomes, particularly in relation to user interface design and system testing.

When Use Cases Add Value 15

Use cases serve as the central hub in the requirements framework, with associated requirements acting as spokes radiating outward This structure emphasizes the importance of use cases as the focal point in both the requirements gathering process and the overall project development lifecycle.

When Use Cases Add Value

Use cases are valuable because they provide clear narratives about the system's functionality in real-world scenarios They allow users to visualize the new system's capabilities and offer feedback early in the process, helping to refine or reject proposed functionalities While this aspect is important, it is just one of the many ways use cases deliver value.

The initial value of use cases emerges when they are defined as user goals supported by the system and compiled into a list This list clarifies the system's capabilities and outlines its purpose, serving as a vital communication tool among various stakeholders involved in the project.

User representatives, executives, expert developers, and project managers will review the list of goals to assess the system's cost and complexity They will prioritize which functions to develop first through negotiation.

Figure 1.1 The “Hub-and-Spoke” model of requirements

In the initial phase of project development, it is essential to establish teams that will utilize a structured framework to assess complexity, cost, timing, and status This framework serves to gather diverse information throughout the project's lifecycle A critical aspect of this process occurs when use case writers collaborate to identify potential issues within a successful scenario By brainstorming and documenting the system's responses to these challenges, the team often discovers unexpected insights that may not have been previously considered by either the team or the stakeholders.

When writing a use case, I often find that the failure conditions reveal new stakeholders, systems, goals, or business rules Documenting how to handle these failures frequently leads to business experts collaborating or communicating to determine the appropriate system response.

Without clearly defined use case steps and proactive failure brainstorming, many errors remain hidden until a programmer encounters them during coding This late discovery of new functions and business rules can lead to rushed decisions, as business experts are often unavailable and time constraints loom Consequently, programmers may resort to improvisation rather than thoroughly researching the intended behavior.

Writing concise one-paragraph use cases significantly saves time while maximizing the benefits of use cases Additionally, individuals who effectively manage failure can identify subtle requirements early, further enhancing efficiency and project outcomes.

Manage Your Energy

To effectively manage your energy while writing, begin with a concise outline instead of diving into all the details at once By focusing on the essence of each use case, you can transition smoothly between topics and maintain your momentum throughout the writing process.

◆ Give your stakeholders a chance to offer correction and insight about priorities early

◆ Permit the work to be split across multiple groups, increasing parallelism and productivity.

People often say, “Give me the 50,000-foot view,” “Give me just a sketch,” or

“We'll add details later.” They mean “Work at low precision for the moment; we can add more later.”

Precision in communication conveys significant meaning with minimal words For instance, stating, “A 'Customer' will want to rent a video” effectively communicates key information to readers Similarly, presenting a concise list of goals for a proposed system provides stakeholders with substantial insights, demonstrating how impactful well-chosen words can be in conveying complex ideas efficiently.

Warm Up With a Usage Narrative

Precision and accuracy are distinct concepts For instance, stating "n is 4.141592" demonstrates high precision but is significantly inaccurate, while saying "it is about 3" reflects low precision yet is accurate This principle applies to use cases as well; as you refine your goals, you may increase precision However, if your initial low-precision goals are incorrect, the effort spent on detailed use cases becomes futile Therefore, it's crucial to ensure your goal list is accurate before investing extensive resources into developing comprehensive use cases.

I divide the energy of writing use cases into four stages of precision, according to the amount of energy required and the value of pausing after each stage:

In defining the functional requirements of the system, it is essential to identify the key actors involved and their corresponding goals A thorough review of this list ensures its accuracy and completeness Subsequently, prioritize these goals and assign them to specific teams and releases, establishing a clear framework for development This process culminates in achieving the first level of precision in the system's functional requirements.

To effectively pursue your selected use cases, outline the main success scenario for each Review these drafts to ensure the system aligns with the interests of key stakeholders This step provides a deeper level of clarity on functional requirements and is relatively straightforward compared to the subsequent levels of detail.

To effectively address failure conditions, first outline the primary success scenario and then compile a comprehensive list of potential failures It's crucial to complete this list before developing strategies for handling each failure, as creating failure management plans requires significantly more effort than simply identifying the failures Many individuals who begin drafting failure handling strategies prematurely may exhaust their energy before fully enumerating all possible failure conditions.

Effective failure handling is crucial for system resilience, as it outlines the expected responses to various failures This process can be challenging and unexpectedly complex, often uncovering obscure business rules or introducing new actors and goals that require support Addressing these issues not only enhances system reliability but also ensures comprehensive coverage of potential scenarios.

Most projects are short on time and energy Managing the precision level to which you work should therefore be a project priority I strongly recommend working in the order given here.

Warm Up with a Usage Narrative

A usage narrative provides a detailed, contextual illustration of a specific actor interacting with a system, showcasing a real-world application Unlike a use case, which outlines broader functional requirements, a usage narrative focuses on a singular instance, offering valuable insights into user experience and system functionality within a project.

18 Chapter 1 Introduction it does not survive into the ofﬁcial requirements document However, it is a very useful device that is worth my describing and your writing

When embarking on a new project, it's common for you or your business experts to have limited experience in writing use cases or to lack a thorough understanding of the system's operations To gain clarity and confidence in the material, it's beneficial to create a vignette that illustrates key moments in the daily life of one of the actors involved.

In a bustling city, renowned actor Ethan Blake battles inner turmoil, driven by an insatiable desire for validation and recognition Haunted by childhood insecurities and a relentless pursuit of perfection, he immerses himself in his roles, believing that each performance could finally earn him the respect he craves As he navigates the highs and lows of fame, Ethan's journey reveals the fragile balance between ambition and personal fulfillment, ultimately leading him to confront the truth that true happiness lies not in accolades, but in self-acceptance and genuine connections.

Brevity is essential for allowing readers to grasp the story quickly, while details and emotional content are crucial for helping various stakeholders—such as requirements validators, software designers, test writers, and training materials writers—understand how to optimize the system to enhance user value.

A usage narrative takes little energy to write and little space, and leads the reader into the use case itself easily and gently Here is an example.

Usage Narrative: Getting “Fast Cash”

Mary efficiently uses an ATM on her way to work, withdrawing $35 with a quick FAST CASH option that dispenses a $20 bill and three $5 bills This convenient transaction allows her to maintain her privacy, as the ATM resets after each use, ensuring her account remains secure She prefers this particular machine for its ability to provide $5 bills, which she needs to pay her daughters' daycare provider, all without leaving her car.

Usage narratives are crafted to help individuals visualize a system's functionality and serve as a preparatory tool before developing detailed use cases Teams often publish these narratives either at the start of all use cases or right before the specific ones they illustrate To enhance collaboration and understanding, one group emphasizes the importance of gathering a user, an analyst, and a requirements writer to animate the narrative, thereby fostering a shared vision of the system in action.

The narrative serves as a foundational framework for outlining the requirements, providing a context that enhances understanding It acts as an anchor for the use case, which simplifies the narrative into a more structured format The use case employs a generic actor name, transforming the specific details of the narrative into a standardized formula for broader application.

Exercises

When analyzing the requirements file outline, it is essential to identify which sections are sensitive to specific use cases and which are more general Engaging in a discussion with another person can reveal differing perspectives on this matter, highlighting the subjective nature of interpreting requirements These differing responses can stem from individual experiences, expertise, and the context in which the requirements are applied, underscoring the importance of collaborative dialogue in understanding and refining project specifications.

To create an effective HTML-linked intranet, it is essential to design a well-structured subdirectory layout that facilitates easy navigation and access to information Incorporating date-stamping conventions is crucial, as it helps users track document versions and updates, ensuring they are referencing the most current information A logical organization of content within the subdirectories, paired with consistent date-stamping, enhances user experience and improves the overall functionality of the intranet.

When considering the use of an ATM, two distinct narratives emerge: one focused on convenience and speed for quick cash withdrawals, and the other emphasizing security and detailed account management for users who prefer to check balances and transfer funds These narratives differ primarily in their user motivations and interactions with the machine, highlighting the varying needs of customers The significance of these differences is crucial for designers, as they must create a system that accommodates both quick transactions and more complex banking tasks, ensuring a user-friendly experience that meets diverse consumer expectations.

1.4 Write a usage narrative for a person going into a brand new video rental store, interested in renting the original version of The Parent Trap.

Craft a usage narrative for your current project and have someone else create one for the same scenario Afterward, compare your narratives and discuss the differences Consider why these variations exist and what steps you might take in response Are these differences a reflection of tolerance in action, or do they signify a more substantial divergence?

This page intentionally left blank

The Use Case Body Parts

The Use Case as a Contract for Behavior

The system serves as a mechanism for executing contracts among diverse stakeholders, with use cases illustrating the behavioral aspects of these agreements Each sentence in a use case is essential as it outlines actions that safeguard or advance the interests of stakeholders These sentences may depict interactions between actors or detail internal system functions necessary to protect stakeholder interests.

Initially, we will examine a use case that highlights the interactions between actors with specific goals After establishing this foundation, we will expand our discussion to encompass the use case as a contractual agreement among stakeholders with varying interests This initial focus serves to illustrate the dynamics at play.

Actors and Goals conceptual model and the second as the Stakeholders and Interests conceptual model.

Interactions between Actors with Goals

A clerk handles service requests via phone calls, aiming to efficiently register and initiate each request in the computer system.

The system is tasked with registering and initiating service requests, ensuring it serves the interests of all stakeholders involved, with the clerk as the primary actor For the time being, we will concentrate on the system's duty to deliver services effectively to this primary actor.

To fulfill its responsibilities, the system establishes subgoals, some of which it can achieve internally while others require assistance from a supporting actor This supporting entity can be a printing subsystem or an external organization, such as a partner company or a government agency.

Chapter 2 The Use Case as a Contract for Behavior

Person or system with goal for SuD System under Design

Other system against which SuD has goal

Figure 2.1 An actor with a goal calls on the responsibilities of another

The supporting actor effectively fulfills its role by delivering subgoals to the system under discussion (SuD) This SuD engages with external actors and accomplishes its subgoals in a sequential manner, ultimately delivering its primary responsibility, which is to fulfill its service promise.

Delivering on a service promise is a primary objective that can be achieved through a series of subgoals These subgoals can be further divided into smaller, more specific sub-subgoals, creating an endless hierarchy of actionable steps This breakdown allows for a detailed analysis of the actions required by all involved parties, reflecting the complexity of achieving service excellence.

Hath smaller fleas that on him prey

And these have smaller still to bite 'em

And so proceed ad infinitum

One of the most challenging aspects of crafting effective use cases is managing the intricate sub-goals involved in the writing process For a deeper understanding, refer to Chapter 5, which discusses the Three Named Goal Levels, and Chapter 7's Guideline 6, which emphasizes the importance of including a "reasonable" set of actions Additionally, Chapter 20's Reminder 6 highlights the necessity of accurately determining the appropriate goal level.

The Actors and Goals conceptual model is versatile, applicable to both businesses and computer systems It encompasses various actors, including individuals, organizations, and computers, allowing for the description of mixed systems that integrate people, companies, and technology This model also facilitates the understanding of software systems that are driven by other computer systems.

Interactions between Actors with Goals 25 calling on a human supporting actor, or an organization calling on a computer system or an individual It is a useful and general model.

When a clerk is on the phone with a customer and the computer system fails, they should quickly switch to a backup method, such as using pencil and paper, to continue taking the customer's request It's essential for the clerk to have a contingency plan in place to ensure they can fulfill their main job responsibilities even when the system is down.

The system may experience a failure in one of its subgoals due to various reasons, such as the primary actor providing incorrect data, an internal malfunction, or the supporting actor not fulfilling its service commitment Understanding how the system should respond in these scenarios is a critical aspect of the SuD’s behavioral requirements.

In certain situations, a system can recover from a failure and continue its normal operations, while in others, it must abandon the goal For instance, if you attempt to withdraw more money than your account permits at an ATM, the transaction will fail Similarly, if the ATM loses connection with the network, the withdrawal will also be unsuccessful However, if you accidentally enter your personal code incorrectly, the system allows you a second opportunity to input it correctly.

Focusing on goal failures and responses to failure makes use cases effective behavioral descriptions of systems and valuable functional requirements Many practitioners of functional and dataflow decomposition highlight this aspect as the primary advantage that use cases provide.

A basic interaction can be likened to sending a message, such as greeting someone in passing, like saying, “Hi, Jean.” In programming, this simple interaction corresponds to a function call in procedural programming, exemplified by print(value) Conversely, in object-oriented programming, it involves one object sending a message to another, as seen in the syntax objectA->print(value).

A sequence of messages, or scenario, represents a complex interaction For instance, when I approach a soda machine and insert a dollar bill for an 80-cent drink, I learn that I need to provide exact change This interaction illustrates the necessity of understanding the machine's requirements for a successful transaction.

3 The machine says “Exact change required.”

4 I curse, push the Coin Return.

5 The machine returns a dollar’s worth of coins.

6 I take the coins (and walk away mumbling).

26 Chapter 2 The Use Case as a Contract for Behavior

When attempting to purchase a cola from a machine, I encountered the issue of needing exact change, which can be viewed as a single step in a larger sequence of events.

1 I went to the company bank and got some money.

2 I tried to buy a cola from the machine, but it needed exact change.

3 I walked down to the cafeteria and bought one there.

Interactions, like goals, can be aggregated or detailed as required Each step within a scenario represents a specific goal, allowing for each step to be expanded into its own use case This indicates that interactions can have layers of complexity, similar to the nature of goals.

Contract between Stakeholders with Interests

The Actors and Goals model provides a framework for writing use case sentences but falls short in detailing the system's internal behavior To address this gap, it is essential to extend the model with the Stakeholders and Interests conceptual model, which emphasizes the importance of defining what to include and exclude in a use case The system under discussion (SuD) functions as a contract among stakeholders, with use cases outlining the behavioral aspects of this contract, even though not all stakeholders may be present during the process.

Figure 2.3 The striped trousers showing subgoals

In a behavior system, the primary actor is typically involved, while other stakeholders, referred to as offstage actors, are not present The system is designed to meet the needs of these offstage actors by performing tasks such as collecting information, conducting validation checks, and maintaining logs.

To ensure stakeholder protection during disputes, ATMs maintain a detailed log of all transactions, including data on failed transactions to identify their status Additionally, the ATM and banking system collaborate to confirm that account holders possess sufficient funds before dispensing cash, ensuring that customers receive only the amount available in their bank accounts.

The use case, as the contract for behavior, captures all and only the behaviors related to satisfying the stakeholders’ interests

To effectively develop a use case, it is essential to identify all stakeholders and articulate their interests regarding the use case's operation This includes understanding the significance of successful completion for each stakeholder and the guarantees they expect from the system With this information, we can outline the use case steps, ensuring that all stakeholder interests are addressed from initiation to completion This process guides us on when to begin and end the writing, as well as what elements to incorporate or omit from the use case.

Many writers overlook the meticulous crafting of use cases, often succeeding despite this oversight While experienced writers may mentally refine casual use cases, they may still omit key details, relying on their ability to identify these gaps during software development This approach can be acceptable for many projects; however, it can lead to significant costs in others, as illustrated by the example of overlooked interests in Section 4.1, Stakeholders.

Figure 2.4 The SuD serves the primary actor, protecting offstage stakeholders

To satisfy the interests of the stakeholders, we need to describe three sorts of actions:

◆ An interaction between two actors (to further a goal)

◆ An internal state change (on behalf of a stakeholder)

The Stakeholders and Interests model introduces a simple yet impactful adjustment to the use case writing process by requiring the identification of stakeholders and their interests This list serves as a crucial reference to ensure that no important elements are overlooked in the use case documentation By incorporating this step, the overall quality and comprehensiveness of the use case are significantly enhanced.

Scope 35

Functional Scope

Functional scope defines the services provided by your system, which will be detailed in the use cases At the project's onset, you may not have a clear understanding of this scope, as determining it often coincides with identifying use cases—making these tasks interconnected Utilizing an in/out list can effectively establish boundaries for what is included or excluded from the scope Additionally, the actor-goal list and use case briefs serve as valuable tools in this process.

The actor-goal list outlines all user goals supported by the system, highlighting its functional capabilities Unlike the in/out list, which details both in-scope and out-of-scope items, the actor-goal list exclusively features the services that the system will provide For example, Table 3.2 presents the actor-goal list for a purchase request tracking system.

To create an effective list, establish a table with three columns: the left column should feature the primary actors involved, the middle column should outline each actor's goals concerning the system, and the right column should indicate the priority or an initial estimate of the release in which the system will address that goal It is essential to regularly update this table throughout the project to ensure it accurately represents the current status of the system's functional boundaries.

Some people add additional columns—trigger, to identify the use cases that will get triggered by time instead of by a person, and business priority, development complexity,

Table 3.1 A Sample In/Out List

Invoicing in any form Out

Producing reports about requests (e.g., by vendor, by part, by person) In

Merging requests into one PO In

Partial deliveries, late deliveries, wrong deliveries In

All new system services, software In

Any nonsoftware parts of the system Out

Identiﬁcation of any preexisting software that can be used In

Functional Scope 37 and development priority, so they can separate the business needs from the development costs to derive the development priority.

The actor-goal list serves as the foundational negotiating framework among the user representative, financial sponsor, and development team, guiding both the project's layout and content.

Managing your energy effectively and operating at lower precision levels is crucial for system analysis The actor-goal list serves as the most basic yet valuable tool for understanding overall system behavior Progressing to a higher precision level involves utilizing the main success scenario or a concise use case brief, which provides more detailed insights into system functionality.

A use case brief is a concise summary, typically two to six sentences long, that outlines the key behaviors and significant activities of a use case, including any notable failures This brief serves as a reminder of the use case's purpose and functionality, making it an essential tool for estimating the complexity of the work involved Teams engaged in development can leverage this summary to better understand the scope and requirements of the use case.

Table 3.2 A Sample Actor-Goal List

Actor Task-level Goal Priority

Approver Complete request for submission 2

Buyer Complete request for ordering 1

Chapter 3 emphasizes the importance of selecting commercial off-the-shelf components (COTS) for project success Some project teams, particularly those with strong internal communication and ongoing user engagement, rely solely on use case briefs for their requirements They effectively manage the remaining requirements through continuous discussions, prototyping, and regular delivery of incremental updates.

To effectively prepare a use case brief, you can present it in a table format, as an extension of the actor-goal list, or incorporate it directly into the initial draft of the use case body A sample of such briefs is provided in Table 3.3, credited to Paul Ford, Steve Young, and Paul Bouzide of Navigation Technologies.

Design Scope

The design scope defines the boundaries of a system, encompassing the hardware and software components we are responsible for creating For instance, when designing an ATM, our focus is on the internal hardware and software contained within the device itself However, the external computer network that the ATM connects to falls outside our design scope, highlighting the importance of clearly delineating what is included in the project.

Table 3.3 Sample Use Case Briefs

Modify the administrative area lattice

Production staff enriches the reference database by incorporating essential administrative area metadata, including elements such as administrative hierarchy, currency, language code, and street types Additionally, contact information for source data is systematically cataloged, representing a specific instance of updating reference data.

Prepare digital cartographic source data

Production teams transform external digital data into a standardized format, ensuring its accuracy and readiness for integration with an operational database This data is then cataloged and securely stored in a digital source library.

Commit update transactions of a shared check- out to an operational database

Staff implements accumulated update transactions to the operational database, ensuring that non-conflicting transactions are successfully committed The application context is aligned with the operational database, and once transactions are committed, they are removed from the application context This process maintains consistency in the operational database while allowing for manual resolution of any conflicting transactions.

From now on, the term "scope" will specifically refer to design scope, as the functional scope is sufficiently outlined by the actor-goal list and use cases Design scope remains a critical focus across all use cases.

Clear communication between writers and readers regarding the design scope of a use case is crucial, as misunderstandings can lead to significant cost increases and contract failures Readers must quickly grasp the intended system boundaries, which are not always evident from the use case name or primary actor alone Different interpretations of the system's scope can arise, especially when multiple writers contribute, leading to confusion among readers Without a shared understanding, one writer may envision the entire corporation as the scope, while another focuses solely on a specific software system or component, resulting in misinterpretations and a lack of clarity in the documentation.

What can we do to clear up the misunderstanding?

To effectively categorize each use case, it is essential to label them according to their design scope, utilizing specific names for the most significant scopes For illustration, let us consider

In our efforts to create a fixed-time, fixed-cost bid for a large system, we reviewed various sample designs When I highlighted the function of a standard printer, the IS expert found it amusing, remarking, “You personal computer people crack me up You think we just use a little laser printer for our invoices? We actually operate a massive printing system, complete with a chain printer and batch I/O We produce invoices in bulk!”

I was shocked “You mean the printer is not in the scope of the system?“

“Of course not! We'll use the printing system we already have.”

Indeed, we found that there was a complicated interface to the printing system

Our system utilized magnetic tape to queue print jobs, allowing the printing system to process the tape overnight It generated a reply tape detailing the printing results, including error records for items that couldn't be printed The next day, our system reviewed these results to identify any discrepancies The design required for interfacing with the tape proved to be substantial and diverged significantly from our initial expectations.

The printing system was intended for our use rather than for design, falling outside our design scope and serving merely as a supporting actor If we hadn't identified this oversight, we would have mistakenly included it in our project scope, leading us to propose a bid for a more extensive system than necessary.

40 Chapter 3 Scope that MyTelCo is designing a NewApp system, which includes a Searcher subsystem. The design scope names are these:

U Enterprise (i.e., MyTelCo) You are discussing the behavior of the entire organization or enterprise in delivering the goal of the primary actor Label the Scope

MyTelCo emphasizes the importance of specifying the organization’s name when discussing use cases, rather than using generic terms like “the company.” When referencing a specific department, it is crucial to mention the department's name Business use cases should be articulated with a focus on the enterprise scope to ensure clarity and relevance.

The U System, also known as NewApp, refers to the hardware or software you are responsible for developing It is designed to interface with various external components, including hardware, software, and human elements.

U Subsystem (i.e., Searcher) You have opened up the main system and are about to talk about how a piece of it works

Using Graphical Icons to Highlight the Design Scope

To enhance reader comprehension of the design scope, consider placing a graphic next to each use case title Although there are currently no tools available for managing icons, creating your own can help minimize confusion In this book, I have labeled each use case with its corresponding icon to facilitate understanding of its scope.

When considering use cases, it's essential to differentiate between black-box and white-box scenarios; a black-box use case focuses solely on the system's outputs without revealing its internal workings, whereas a white-box use case provides insight into the system's internal structure and processes.

Figure 3.1 Design scope can be any size

A business use case encompasses the entire enterprise, represented visually as a building If you consider the organization as a black box, depict it in grey; however, if you focus on the specific departments and staff within the organization, use white to illustrate this perspective.

A Longer Writing Sample: “Handle a Claim” at Several Levels

“HANDLE A CLAIM” AT SEVERAL LEVELS

I would like to thank the people at Fireman’s Fund Insurance Corporation in Novato,

California, for allowing me to include Use Cases 19 through 23 as writing samples *

They were written by claims-handling professionals directly from the ﬁeld, working with business analysts from the IT department and the technical development staff.

The collaboration between field staff and IT personnel led to valuable insights, as the field staff offered perspectives on system usage that IT could not have anticipated In turn, the IT team assisted the field staff in refining their writing for clarity This partnership effectively integrated field, corporate, and technical viewpoints, enhancing overall communication and understanding.

The writing team included Kerry Bear, Eileen Curran, Brent Hupp, Paula Ivey,

Susan Passini, Pamela Pratt, Steve Sampson, Jill Schicktanz, Nancy Jewell, Trisha

Magdaleno, Marc Greenberg, Nicole Lazar, Dawn Coppolo, and Eric Evans They demonstrate that usage experts with no software background can work with IT staff in writing requirements

This article presents five use cases that exemplify the design scopes and goal levels discussed previously Each use case is accompanied by commentary highlighting key points of interest and potential areas of contention, while also demonstrating effective writing style for outlining steps and extensions.

The article begins by illustrating a cloud-level, white-box business use case that outlines the processes for managing a claim It demonstrates how objectives are refined from broad "company operations" to specific "all computer systems" and ultimately to "the system under design." Key phrases highlight connections to additional use cases, and the template has been slightly adjusted to position the main success scenario near the top for improved readability.

Use Case 19 focuses on the company's operations, emphasizing that the computer system is not explicitly mentioned This use case serves as a foundation for the business to align its procedures and explore how technology can enhance its operations Currently, it is in the initial sketching phase, where the main success scenario appears straightforward, illustrating optimal functioning However, the real insights will emerge from analyzing failure conditions and how the company leverages this information to enhance its IT support for operations, highlighting the importance of stakeholder involvement.

A Longer Writing Sample: “Handle a Claim” at Several Levels 71

Use Case 19 Handle a Claim (Business)

Context of Use: Claims Adjuster handles claim.

Trigger: A claim is reported to insurance company.

1 A reporting party who is aware of the event registers a loss to insurance company.

2 Clerk receives and assigns the claim to a claims adjuster.

3 The assigned Claims Adjuster conducts an investigation evaluates damages sets reserves negotiates the claim resolves the claim and closes it

Success Guarantee: Claim is resolved and closed.

Insurance company Divisions who sell insurance company policies

Insurance company Customers who have purchased policies

Department of Insurance, which sets market conduct

Claimants who have a loss as a result of act of an insured

In this business use case, the focus remains on the company's operations, but the objectives are set at a more granular level compared to previous examples.

Case 19 It shows an adjuster’s work that may take days, weeks, or months It is a kite- level summary use case because it contains many single-sitting activities.

The article highlights that the writer omits direct references to the computer, focusing instead on the adjuster's goals This approach requires the team to creatively envision how computers can facilitate these objectives, serving as the foundational inspiration for their innovative processes.

Step 7 was added because of the interests of the Department of Insurance.

72 Chapter 5 Three Named Goal Levels

Use Case 20 Evaluate Work Comp Claim

Level: White (summary, above single user goal level)

Context of Use: Claims Adjuster completes thorough evaluation of the facts of a loss. Primary Actor: Claims Adjuster

Please Note: Investigation has ideally been completed prior to evaluation, although the depth of the investigation can vary from claim to claim.

1 Adjuster reviews and evaluates the medical reports, lien documents, beneﬁts paid to date, and other supporting documents.

2 Adjuster rates the permanent disability by using a jurisdictional formula to determine % of disability.

3 Adjuster sums the permanent disability owed, taking credit for advances and payment of liens to arrive at the claim’s full value.

4 Adjuster determines the ﬁnal settlement range.

5 Adjuster checks reserves to make sure they are in line with settlement range.

6 Adjuster seeks authorization for settlement and reserve increase if above his/her authority level.

8 Adjuster sends any correspondence and/or documentation to parties involved as necessary.

9 Adjuster continues to document ﬁle regarding all settlement activity.

Frequency of Occurrence: Every claim is evaluated; this can happen several times a day.

Success Guarantee: Claim is evaluated and settlement range determined.

Minimal Guarantee: Additional investigation or medical evaluations are completed until claim is ready to be re-evaluated for settlement.

Adjuster—wants lowest legitimate settlement.

Attorney (defense and plaintiff) of Insureds.

The Division of Insurance, along with state governing offices, aims to ensure fairness in the administration of benefits and the settlement process Each state has its own governing department dedicated to overseeing these procedures, emphasizing the importance of compliance and equitable outcomes.

Open Issues: Jurisdictional issues will have to be addressed when writing the business rules.

A Longer Writing Sample: “Handle a Claim” at Several Levels 73

Use Case 21 may have initially appeared vague to many project members, but it proved valuable in several ways It effectively connects various user-goal use cases, illustrating their alignment with business guidelines By detailing the processes of closing, purging, and archiving a claim, it clarifies aspects that were previously unclear to some team members While these steps do not directly create programming tasks, they provide essential contextual information that enhances the overall understanding of claim handling for all stakeholders involved.

The official documentation clarified previously unknown business rules for the team, which had wasted three work-hours the day before attempting to decipher them By documenting this use case, the team was able to save numerous hours in subsequent discussions on the subject.

This article serves as an introductory guide for a diverse audience, including company executives and new hires It highlights essential processes for executives while providing newcomers with insights into the company's operations and user-goal use cases Notably, Extension *a1 addresses a failure-handling use case that required input from the technical group rather than the claims adjustors.

Use Case 21 Handle a Claim (Systems) +

Scope: “System” means all computer systems combined $

Context of Use: Customer wants to get paid for an incident.

1 Customer reports a claim (paper, phone, or fax) to Clerk.

2 Clerk ﬁnds the policy, registers loss in System, and assigns an Adjuster.

3 Adjuster investigates the claim and updates the claim with additional information

4 Adjuster enters progress notes over time.

5 Adjuster corrects entries and sets monies aside over time.

6 Adjuster receives documentation including bills throughout the life of the claim and enters bills.

7 Adjuster evaluates damages for claim and documents the negotiation process in

8 Adjuster settles and closes claim in System.

9 System purges claim 6 months after close.

10 System archives claim after time period.

*a At any time, System goes down:

1a1 Insurance company requests missing information.

1a2a Claimant does not supply information within time period:

1a2a1 Adjuster closes claim in System.

2a Claimant does not own a valid policy:

2a1 Insurance company declines claim, notiﬁes claimant, updates claim, closes claim.

3a No agents are available at this time:

3a1 (What do we do here?)

8a Claimant notiﬁes adjuster of new claim activity:

8a1 Clerk reopens claim Reverts to step 3.

Technology and Data Variations List:

Frequency of Occurrence: To be documented.

Success Guarantee: Claim is closed, settled, and archived.

Minimal Guarantee: Claim closed but may be reopened later.

The company—make smallest accurate settlement.

Department of Insurance—ensure correct procedures.

Data Descriptions: Will be deﬁned in other use cases.

UI Links: To be documented.

Open Issues: What are the time periods for archiving claims?

COMMENTARY ON USE CASE 22 This is one of the most complex use cases I have seen.

It shows why use cases should be written in natural-language prose.

The primary source of complexity in customer service interactions lies in the sequencing of information A clerk must navigate a conversation with a distressed customer, entering details in any order while adhering to a standard questioning framework Concurrently, the computer system processes the information in real-time, retrieving customer records and assigning claim numbers and adjusters The writers developed multiple versions of this use case to clarify the intricacies involved.

In the process of refining the "Handle a Claim" use case, the team reached a point of diminishing returns after multiple revisions, ultimately deciding to finalize their work This use case repeatedly utilizes the "Find a Whatever" function with varying search criteria and items To streamline the process, the team devised an innovative approach that eliminated the need to rewrite standard search steps, such as matching lists and sorting criteria.

The handling of extension *a revealed unexpected requirements due to power failures, introducing the concept of intermediate saves This new feature allowed clerks to search for temporarily saved losses later, raising questions about the storage and retrieval of these entries The situation culminated in failure condition 6b, which addressed time-outs on temporarily saved losses and prompted the critical inquiry: “What are the business rules for a temporarily entered loss that cannot be committed due to missing key information but should not be deleted because it meets the minimum entry criteria?” After considering unacceptable alternatives, the team ultimately reached a viable solution.

Extension 1c illustrates the concept of failures within failures, which could have been developed into a distinct use case However, the writers opted against this to avoid adding complexity to the existing use case set, as a new use case would require tracking, review, and maintenance Consequently, they chose to classify it as an extension of the extension This approach is common among many, as they often prefer to limit the depth of use case extensions before considering them as separate use cases.

Extension 2–5a illustrates the flexibility of the medium, highlighting that the condition can occur at any point between steps 2 and 5 Instead of repeating the writing for each potential occurrence, which would be inefficient, the optimal approach is to present both 2–5a and 2–5b, ensuring clarity for readers.

Scope: “System” means the claims-capturing computer system $

Context of Use: Capture loss fully.

Preconditions: Clerk has already logged in.

Trigger: Clerk has already started entering loss.

Success Guarantee: Loss information is captured and stored

Stakeholders and Interests: As before

Preconditions, Triggers, and Guarantees 81

Preconditions

The precondition of a use case specifies the conditions that must be met before the use case can begin, ensuring that certain criteria are established and validated by the system Once these preconditions are confirmed, they are not re-evaluated during the execution of the use case A typical example of a precondition is that the user must be logged in and authenticated.

A precondition signifies that a prior use case must be executed to establish the necessary setup; for instance, placing an order requires the user to be logged in To clarify the relationship between these use cases, I often develop a higher-level use case that encompasses both "Place an Order" and "Log On." This approach helps readers understand how these two processes interconnect, providing a clearer overview of their dependencies.

Use the Application In this example, we get the following structure (I abbreviate the template to show just the relevant parts) Note the goal levels of the three use cases.

Use Case: Use the Application

82 Chapter 6 Preconditions, Triggers, and Guarantees

Use Case: Place an Order

Precondition: Clerk is logged on.

Not everyone adopts my approach of linking higher-level use cases to their lower-level counterparts Consequently, you may only recognize actions like "Log On" and "Place an Order" in the previous example It is essential to infer from the text that the precondition is accurate and will be upheld.

In this example, we illustrate a use case where a condition is established in one step, which is then utilized in a subsequent sub use case The sub use case assumes the condition is valid and does not perform any error checks.

Use Case: Place an Order

Precondition: Clerk is logged on.

1 Clerk identiﬁes customer, system pulls up customer record.

Precondition: Customer is established and known to system; order contents are known.

1 System calculates base charge for order.

2 System calculates discount for customer.

This example demonstrates how a specific use case depends on information obtained from a previous calling use case The author of Calculate Charges has identified the available information, allowing for the effective reference to customer details.

The use case "Calculate Charges" may raise skepticism among readers, as it has been labeled as indigo without sufficient justification for its standalone status To validate its classification, it is essential for the writer to explore and reveal the intricate interactions that support its significance.

To enhance user experience, I will categorize interesting failure cases as black (clam) using icons, signaling the need to merge this information back into the "Place an Order" section and remove any redundant text.

Write a precondition as a simple assertion about the state of the world at the moment the use case opens Suitable examples are

Precondition: The user is logged on.

Precondition: The customer has been validated.

Precondition: The system has already located the customer's policy information.

A common mistake is to write into the precondition something that is often, but not necessarily, true

When drafting a Request Benefits Summary with the primary actor being the Claimant, it's important to note that submitting a claim or bill prior to requesting the benefits summary is not a requirement The system does not guarantee that a claim has been submitted, and it is not essential for the Claimant to have done so Claimants should have the ability to request their benefits summary at any time, making it inaccurate to state that a precondition for this request is the submission of a bill.

Minimal Guarantees

Minimal guarantees represent the essential commitments a system makes to stakeholders, especially when the primary objective cannot be met While these guarantees are relevant when the goal is achieved, they become particularly significant when the main goal is set aside Typically, multiple stakeholders, such as users, the system provider, and potentially government regulatory bodies, need to be considered in establishing these minimal guarantees.

When drafting the Minimal Guarantees section, avoid detailing every potential failure of the use case, as there are numerous unrelated failure scenarios Instead, focus on the system's promises, since all failure conditions and their handling are addressed in the extensions section Maintaining synchronization between these two lists can be cumbersome and prone to errors.

A minimal guarantee in systems is the logging of progress, which is essential yet often overlooked in requirements Transaction failure logging is not straightforward and can be forgotten by developers However, these logs are vital for both system owners and users, as they enable the resumption of transactions after disruptions and assist stakeholders in resolving disputes To ensure the necessity of logging is recognized, use case writers should explore stakeholder interests and consider potential failure scenarios during brainstorming sessions.

84 Chapter 6 Preconditions, Triggers, and Guarantees

The minimal guarantees consist of straightforward assertions that will hold true upon the completion of any use case execution, ensuring that the interests of all stakeholders are met.

Minimal Guarantee: Order will be initiated only if payment received.

To ensure accurate processing, if the minimum required information is not captured during a call, the partial claim will be discarded without any log entry However, when the minimum information is successfully recorded, the partial claim will be saved and logged according to established business rules.

The pass/fail test for a minimal guarantee is that the stakeholders agree that their interests are protected under failure conditions for this goal.

Success Guarantee

The success guarantee outlines the interests of stakeholders that are fulfilled upon the successful completion of a use case, whether at the conclusion of the main success scenario or an alternative path It is typically appended to the minimal guarantees, which confirm that basic conditions are met alongside additional criteria, including the primary goal outlined in the use case title Similar to minimal guarantees, the success guarantee is expressed as a series of straightforward assertions that reflect the satisfaction of each stakeholder's interests at the end of a successful use case execution.

Success Guarantee: The claimant will be paid the agreed-upon amount, the claim closed, the settlement logged.

Success Guarantee: The ﬁle will be saved.

Success Guarantee: The System will initiate an order for the customer, will have received payment information, and logged the request for the order.

The pass/fail test for the success guarantee section is that the stakeholders agree that their interests have been satisﬁed.

To ensure success, identify potential stakeholder dissatisfaction by asking, "What could lead to this stakeholder feeling unhappy after a successful outcome?" This question typically yields straightforward answers Once identified, articulate the opposite of those concerns to create a clear success framework For practical application, refer to Exercise 6.4 and the accompanying discussion in Appendix B.

Triggers

The trigger defines the event that initiates a use case, which can either occur before the first step or serve as that first step itself To date, there hasn't been a compelling argument supporting the idea that one specific form of trigger is universally applicable across all scenarios.

Exercises 85 any confusion from choosing one way over the other You will have to develop your personal or project style.

An ATM system activates solely when a user inserts their card, making the action of inserting the card the true trigger for the transaction This initial step is essential in the use case, as it signifies the user's intent to engage with the ATM.

Use Case: Use the ATM

1 Customer inserts card with bank ID, bank account, and encrypted PIN.

Imagine a clerk stationed at a workstation, where various graphical icons represent different application programs When a customer calls with a specific request, the clerk can respond using one of two forms; for illustration, I will demonstrate using the second method.

Trigger: Customer calls in a complaint.

1 Clerk calls up the application.

2 The system brings up the clerk’s recent complaints list.

Scenarios and Steps 87

The Main Success Scenario

When explaining concepts, we typically begin with a simple description, followed by a clarification that introduces a complication For instance, we might say, “When such-and-such occurs, what really happens is ” This approach helps to provide a clearer understanding of the topic by addressing nuances.

A clear explanation style effectively conveys a crisscrossing storyline that serves as a use case We begin by outlining a straightforward scenario where the primary actor achieves their goal while satisfying all stakeholders' interests, which constitutes the main success scenario Additionally, we explore alternative success pathways and address potential failures through various extensions of this narrative.

The main success scenario and all scenario extensions sit within a structure that consists of the following:

A scenario operates under specific conditions, which include a precondition and a trigger for the main success scenario In the case of an extension scenario, the relevant extension condition is defined, possibly referencing the step number or location within the scenario where this condition is applicable.

A successful use case should align with the interests of stakeholders, representing a clear goal to achieve In extension scenarios, the objective is to either fulfill the primary use case goal or to reintegrate into the main success scenario after addressing specific conditions.

U A set of action steps These form the body of the scenario and follow the same rules in every scenario or scenario fragment

U An end condition The goal is achieved at the end of the main success scenario A scenario fragment may end with the goal being either achieved or abandoned.

In a use case template, potential extensions are documented as scenario fragments, with main success scenario extensions located in the designated extensions section Additionally, any extensions to these extensions are integrated either inline within the extension body or immediately following it.

Here are two extracts from Use Case 1, which I have stripped down to show just the similarities of their surrounding structures.

Here is a main success scenario:

Use Case: Buy Stocks over the Web

Trigger: User selects “buy stocks”:

1 User selects to buy stocks over the web.

2 PAF gets name of web site to use (E*Trade, Schwab, etc.) from user.

4 User browses and buys stock from the web site.

5 PAF intercepts responses from the web site and updates the user's portfolio.

Here is an extension to it:

3a Web failure of any sort during setup:

3a1 System reports failure to user with advice, backs up to previous step.

3a2 User either backs out of this use case or tries again.

In this chapter, we look in detail at the body of the scenario, which consists of action steps.

Each scenario is structured as a series of actions aimed at achieving specific goals by different participants While we refer to these actions as a sequence for simplicity, it is important to note that steps may occur simultaneously, be executed in varying sequences, be repeated, or even be optional.

As noted in Section 2.2, Contract between Stakeholders with Interests, on page 29, any one step will describe

U An interaction between two actors (“Customer enters address”)

U A validation step to protect an interest of a stakeholder (“System validates PIN code”)

U An internal change to satisfy an interest of a stakeholder (“System deducts amount from balance”).

Here is an example of a typical main success scenario, borrowed from Use Case

22, Register a Loss, on page 75 Notice that steps 1, 3, and 5 through 8 are interactions, step 4 is a validation, and steps 2 and 9 are internal changes.

1 Clerk enters insured's policy number or else name and date of incident

2 System populates available policy information and indicates claim is matched to policy.

3 Clerk enters basic loss information.

4 System conﬁrms there are no competing claims and assigns a claim number.

5 Clerk continues entering loss information speciﬁc to claim line.

6 Clerk has System pull other coverage information from other computer systems.

7 Clerk selects and assigns an Adjuster.

8 Clerk conﬁrms he/she is ﬁnished

9 System saves and triggers acknowledgment to be sent to Agent.

Each action step is written to show a simple, active action I liken it to describing a soccer match: Person 1 kicks ball to person 2; person 2 dribbles ball; person 2 kicks ball to person 3.

Mastering the three types of action steps is crucial for establishing a consistent writing style This approach applies uniformly across all components of a use case, including main success scenarios, extensions, business processes, and system interactions, regardless of whether the use case is high-level or low-level.

Action Steps

A well-structured use case consists of clearly defined action steps, each presented in a consistent grammatical form These actions typically describe a single actor completing a task or transferring information to another actor, ensuring clarity and coherence throughout the document.

User enters name and address.

At any time, user can request the money back.

The system veriﬁes that the name and account are current.

The system updates the customer’s balance to reﬂect the charge.

Usually the timing can be omitted, since steps generally follow one after the other

When writing action steps, ensure to maintain clarity and consistency, incorporating minor variations as demonstrated in the use case samples Each step should embody essential characteristics, including specificity, actionable language, and a logical sequence to enhance understanding and effectiveness.

Use Simple Grammar

The sentence structure should be absurdly simple:

Subject verb direct object prepositional phrase.

The system deducts the amount from the account balance.

Many people inadvertently omit the first noun in their sentences, leading to confusion about who is performing the action, such as who has the ball This can result in poorly structured sentences that make the narrative difficult to follow.

Guideline 2: Show Clearly “Who Has the Ball”

Imagine a group of friends playing soccer, where one player passes the ball to another, who then dribbles before sending it to a third player Occasionally, the ball gets muddy, prompting one of the players to clean it off This dynamic illustrates teamwork and the importance of maintaining the equipment for an enjoyable game.

In a structured scenario, each step involves an actor who "has the ball," making them the subject of the sentence, typically positioned as the first or second word This "ball" represents the message and data exchanged between actors.

The actor with the ball has three options: he can kick it to himself, pass it to a teammate, or wipe off the mud Approximately fifty percent of the time, this action leads to another play.

Action Steps 91 actor having the ball Ask yourself, “At the end of the sentence, who has the ball?” The answer should always be clear in the writing.

Guideline 3: Write from a Bird's Eye View

Beginning use case writers, especially programmers, often draft use case documents from the system's perspective, narrating interactions in a self-reflective manner Their writing typically includes straightforward commands like, "Get ATM card and PIN number" and "Deduct amount from account balance."

Instead, write the use case from a bird's eye view:

The customer puts in the ATM card and PIN.

The system deducts the amount from the account balance.

Some writers like to use another style that has the quality of a play, describing actors performing their parts.

Customer: Puts in the ATM card and PIN.

System: Deducts the amount from the account balance.

Note that the information is the same in both styles.

Guideline 4: Show the Process Moving Forward

The progress achieved in a single step is directly linked to the elevation of the use case goal In scenarios involving summary or white use cases, each step can significantly advance the overall user objective Conversely, in subfunction use cases, the progress tends to be more incremental, resulting in smaller advancements toward the goal.

When a user presses the tab key, it typically indicates either a complex use case involving deep indigo or black themes, or the writer has opted for an action that is too minor to warrant detailed description.

The mistake of choosing very small steps shows up in the length of the use case.

Use cases with 13 or 17 steps often lack clarity and effectiveness, as merging smaller steps can enhance readability and maintain essential information Typically, a well-structured use case features no more than 9 steps in the main success scenario, making it easier to understand and follow.

To identify a higher-level goal for a step, inquire, "Why is the actor doing that?" This approach, detailed in the section on Raising and Lowering Goal Levels, often reveals the necessary goal for the step It may require multiple iterations of the question to uncover the desired answer.

Why is the user hitting the tab key? To get to the Address ﬁeld

Why is she trying to get to the Address ﬁeld? Because she has to enter her name and address before the system will do anything.

To utilize the system effectively, she needs to input her name and address, which is likely related to the specific use case she aims to achieve.

Thus, the action sentence that moves the process distinctly forward is

User enters name and address.

Guideline 5: Show the Actor’s Intent, Not the Movements

One common mistake in use case writing is detailing the user's movements within the system's user interface, often referred to as interface detail descriptions These descriptions negatively impact the requirements document by making it unnecessarily lengthy, fragile, and overly constrained.

U Longer documents are harder to read and more expensive to maintain.

U The dialog being described is probably not a requirement but just how the writer imagines the user interface design at that moment.

U The dialog is brittle in the sense that small changes in the system design will in- validate the writing.

A user interface designer is responsible for developing an effective user interface that enables users to fulfill their intended use cases Specific actions and interactions should be incorporated into the design process rather than detailed in the functional requirements document.

In the requirements document, the focus is on detailing the interface's intention, which conveys the user's intent and summarizes the information exchanged between actors Larry Constantine and Lucy Lockwood discuss this concept in their book, "Software for Use," where they introduce the term "essential use cases" to refer to high-level system use cases that illustrate interface intentions.

Data flowing in one direction is often consolidated into a single action step This common writing mistake can be corrected for clarity and coherence.

1 User enters name and address.

When passing more than three data items, it's advisable to list each item on a separate line in a tabbed format This approach not only improves readability but also facilitates quicker drafting of use cases While both methods are effective, the first option is preferable during initial writing stages, whereas the second method is better suited for ensuring accuracy in traceability and testing.

1 User enters name, address, phone number, secret information, emergency contact phone number.

Guideline 6: Include a “Reasonable” Set of Actions

Ivar Jacobson has described a step in a use case as representing a transaction With this phrasing, he captures four pieces of a compound interaction (see Figure 7.1.):

1 The primary actor sends request and data to the system.

2 The system validates the request and the data.

3 The system alters its internal state.

4 The system responds to the actor with the result.

Figure 7.1 A transaction has four parts

Our System Request with Data

Idiom: “Do Steps x–y until Condition”

Exercises

7.1 Write a scenario for one of your use cases in two ways: using interface detail description and using intention description Discuss the differences between the two.

7.2 Write the main success scenario for the task-level use case Withdraw Money Using Fast Cash

7.3 Write the main success scenario for one strategic use case and one task use case for the PAF system.

7.4 Your junior colleague sends you the following Using the reminders you have learned so far, send back a critique and corrections.

This use case describes the process by which users log in to the order-processing system It also sets up access permissions for various categories of users.

1 The use case starts when the user starts the application.

2 The system will display the Login screen.

3 The user enters a username and password.

4 The system will verify the information.

5 The system will set access permissions.

6 The system will display the Main screen.

7 The user will select a function.

8 While the user does not select Exit loop

9 If the user selects Place Order, Use Place Order.

10 If the user selects Return Product, Use Return Product.

11 If the user selects Cancel Order, Use Cancel Order.

12 If the user selects Get Status on Order, Use Get Status.

13 If the user selects Send Catalog, Use Send Catalog.

14 If the user selects Register Complaint, Use Register Complaint.

15 If the user selects Run Sales Report, Use Run Sales Report. end if

16 The user will select a function. end loop

A comprehensive use case must encompass all scenarios, including both successful and unsuccessful outcomes While we are familiar with crafting the primary success scenario, it is essential to incorporate additional scenarios to provide a complete picture.

Writing each scenario separately may align with the striped trousers metaphor, but this method can lead to significant maintenance challenges As discussed in Chapter 2, any modification to a scenario requires updating all other scenarios that share the same content, creating a cumbersome process for writers.

An alternative approach is to incorporate if statements throughout the text, such as stating, "If the password is good, the system does otherwise, the system does " While this method is legally acceptable and utilized by some for writing use cases, it can confuse readers The complexity increases with nested if conditions, making it challenging for readers to follow the behavior, especially as most use cases involve numerous branching points.

An effective method for organizing text involves outlining the primary success scenario in a straightforward sequence from the trigger to completion, followed by developing scenario extensions for each branching point This approach appears to be the most advantageous among the three options.

Extension Basics

Extensions function by identifying branching points in the main success scenario based on specific conditions For each branching point, it is essential to document the condition and outline the subsequent steps that address it Typically, many extensions conclude by remerging with the primary success scenario.

The extension is really a stripped down use case It starts with a condition—the one that makes it relevant It contains a sequence of action steps describing what happens

Chapter 8 discusses the 100 extensions that culminate in either the delivery or abandonment of the extension goal It also addresses potential challenges and considerations that may arise during the process of managing these extensions.

The most intriguing system requirements are found within these extensions, where the team's familiar success scenarios contrast with the often unknown failure handling business rules Requirements writers frequently conduct research to determine the appropriate system responses, which can lead to the introduction of new actors, use cases, or extension conditions.

Here is a fairly typical discussion that illustrates my point.

“Suppose there is a sudden network failure What do we do?”

“Got it Hey, if the network goes down, what’s supposed to happen when it comes up again?”

System restarts following network failures are essential, as they allow the system to recover, retrieve logs, and determine whether to complete or abort transactions.

“Yes, but what if the log is corrupt? Then what’s the system supposed to do?”

“I don’t know Let’s write it as an Open Issue and continue.”

This discussion revealed a new application and highlighted the necessity of examining business policies It's crucial not to underestimate the importance of addressing these extensions, as developers may encounter similar situations during programming Identifying new business rules at this stage can be costly, making requirements gathering the ideal time for thorough research.

I recommend working in three phases:

1 Brainstorm and include every possibility you and your colleagues can conjure up.

2 Evaluate, eliminate, and merge the ideas according to the guidelines in Section 8.2.

3 Sit down and work your way through the system’s handling of each of these conditions.

The Extension Conditions

Extension conditions refer to the circumstances that lead the system to exhibit different behaviors Unlike failure or exceptions, the term "extension" encompasses both alternative success scenarios and failure conditions.

Here are two snippets that illustrate success and failure paths in extensions.

4 User has the system save the work so far.

4a System autodetects the need for an intermediate save:

The system can autonomously detect the need for an intermediate save instead of relying solely on the user to save their progress If the save—whether initiated by the user or triggered by autosave—encounters an execution failure, specific actions should be taken to address the issue.

3 The system goes through the document, checking every word against its spelling dictionary.

4 The system detects a spelling mistake, highlights the word, and presents a choice of alternatives to the user.

5 The user selects one of the choices for replacement The system replaces the highlighted word with the user’s replacement choice.

4a The system detects no more misspellings through the end of the document:

4a1 The system notiﬁes the user, terminates the use case.

5a User elects to keep the original spelling:

5a1 The system leaves the word alone and continues.

5b User types in a new spelling not on the list:

5b1 The system revalidates the new spelling, returns to step 3.

Brainstorm All Conceivable Failures and Alternative Courses

It is important to brainstorm and get good coverage of the extension conditions before writing how to handle them This brainstorming is tiring, and so is documenting

Chapter 8 discusses the challenges of managing extensions, highlighting that conceptualizing a single extension and understanding the system's response can be energy-intensive As one navigates through multiple extensions, the mental effort increases significantly, potentially hindering the ability to generate additional extension conditions effectively.

By brainstorming various success and failure scenarios, you create a foundational list that supports your work for hours or days This approach allows you to step away for a break, whether at lunchtime or overnight, and easily resume your progress when you return.

Brainstorm all the possible ways in which the scenario can fail or alternate ways it can succeed Be sure to consider all of these:

U An alternate success path (Clerk uses a shortcut code).

U The primary actor behaving incorrectly (Invalid password).

U Inaction by the primary actor (Time-out waiting for password).

U Every occurrence of the phase “the system validates,” implying that there will be an extension to handle validation failure (Invalid account number).

U Inappropriate or lack of response from a supporting actor (Time-out waiting for response).

U Internal failure within the system under design, which must be detected and handled as part of normal business (Cash dispenser jams).

U Unexpected and abnormal internal failure, which must be handled and will have an externally visible consequence (Corrupt transaction log discovered).

U Critical performance failures of the system that you must detect (Response not calculated within 5 seconds).

Many individuals engage in brainstorming to outline the progression of a scenario from start to finish, aiming for comprehensive coverage of potential issues This process often reveals numerous possible failures that could occur Exercise 8.1 offers an opportunity to brainstorm potential failures, with answers available in Appendix B for reference Notably, two students, John Colaizzi and Allen Maxwell, identified nearly three times as many failures as I did in my response How many can you uncover?

Guideline 11: Make the Condition Say What Was Detected

When documenting system detections, focus on the observable actions rather than assumptions about user behavior For instance, instead of stating that a customer forgot their PIN, it is more accurate to report what the system detects: an exceeded time limit Therefore, the appropriate phrasing would be "Time limit exceeded waiting for PIN to be entered" or "PIN entry time-out." This approach ensures clarity and precision in reporting system events.

The term "condition" typically refers to a specific observation or finding To clarify that it is not an action step, I prefer to use a colon (:) following the condition This simple practice helps prevent misunderstandings.

The customer does not respond (time-out):

Cash did not eject properly:

When outlining numbered steps, indicate the specific step where a condition can be identified by adding a letter (e.g., 4a) The letters do not imply a sequence, allowing for multiple extension conditions to be associated with a single action step.

If the condition can occur at several steps and you feel it important to indicate that, simply list those steps:

If the condition can occur at any time, use an asterisk (*) instead of the step number List the asterisk conditions before the numbered conditions.

*b User walked away without notice (time-out):

When considering the point of failure in a system, it's less important to debate whether it occurs during data entry or data validation While one could argue that errors can arise at either stage, focusing on this distinction is not productive Typically, I associate the failure with the validation step when it exists.

When crafting content without numbered steps, it is essential to provide detailed descriptions of conditions to guide the reader effectively To enhance readability, insert a blank line before each condition and emphasize it using italics, making it easily noticeable For an illustrative example, refer to Use Case 32, Manage Reports, on page 146.

When brainstorming, it's normal to generate more ideas than you ultimately implement The goal is to identify all potential scenarios the system may face in this use case, allowing for a comprehensive exploration of possibilities You can refine and narrow down the list in the later stages of the process.

Your list may still be incomplete as you might identify additional failure conditions while drafting extension scenarios or incorporating new validation steps into the use case This is normal, so focus on brainstorming effectively and remember to update your list as new insights arise.

The goal of rationalizing activities is to create a concise list of extension conditions, highlighting only the necessary situations that the system must address A lengthy requirements document can be challenging to read, and redundant descriptions complicate maintenance By consolidating extension conditions, you not only streamline your writing but also enhance the reading experience for your audience.

After brainstorming, develop a concise main success scenario along with a comprehensive list of conditions to evaluate Carefully review this list to eliminate unnecessary conditions and consolidate those with similar impacts on the system.

The opposite of good extension brainstorming happened on an important, large project I worked on

Many developers often overlook the potential issues that may arise from encountering bad data in a database, hoping that other teams will manage these problems Unfortunately, this assumption can lead to significant consequences For instance, shortly after the initial delivery of a new sales system, a senior vice president decided to check on its performance with a major customer, only to be met with the disheartening message, “No data found.” His reaction was far from positive, highlighting the critical need for thorough data validation and error handling in software development.

Make the Condition Say What Was Detected

Extension Handling

In basic scenarios, a sequence of steps addresses specific conditions, while in more complex situations, the extension serves as a mini use case The trigger for this extension is the condition, with the aim of either achieving the use case goal or recovering from any encountered failures The process consists of a series of action steps, which may include additional extensions Similar to a use case, the extension can conclude with either the successful delivery of its goal or its abandonment, highlighting the practical benefits of this similarity in simplifying intricate extensions.

Upon detecting the condition, immediately implement the necessary corrective measures to address the issue Ensure that all actions align with the established guidelines for achieving the desired outcome, utilizing clear and concise language Focus on maintaining a proactive approach, emphasizing the importance of swift intervention to mitigate any potential risks Document each step taken to resolve the situation, ensuring that the process remains transparent and effective, ultimately leading to a successful resolution.

Keep writing until you reach a place where the main scenario can be rejoined or the use case fails

Typically, the scenario fragment ends in one of the following four ways:

The step that branched to the extension has been ﬁxed and replaced At the end of the extension handling, the situation is as though the step had succeeded

3 User activates web site URL.

3a1 User searches for web site

The system provides the actor with a second opportunity, resetting the process to the initial step after the extension handling For instance, the system will prompt a revalidation of the password.

4a1 System notiﬁes user, requests password again.

The use case ends because of total failure.

4c Invalid password entered too many times:

4c1 System notiﬁes user, terminates user session.

The behavior follows a completely different path to success.

3a User runs personal macro to complete processing:

In the initial scenarios, the next steps in the extension are clear to the reader, as it is evident that the process will either restart or continue Conversely, in the final scenarios, simply stating "Fail" or "Use case ends" suffices, as the steps illustrate how the system aligns with the stakeholders' interests.

Most extensions lack clarity on the story's progression following the extension, as the direction is often evident Repeatedly stating "Go to step N" after each extension can hinder the readability of the text However, in instances where the transition to a different part of the main success scenario is not clear, the final step may include a directive to "Go to step N."

Examples of all of these situations can be found in the various writing samples throughout the book

When applying the numbering style outlined in this book, ensure that the action steps detailing how to address the condition are indented, and restart the numbering at 1 after the letter These action steps should adhere to all previously provided style guidelines.

2a1 System notifies customer, asks for a new amount

Volker Schaberg of Software Futures CCH introduced a streamlined numbering convention, where writers eliminate the leading number-letter pair and begin directly with a dot followed by a number.

1 System notifies customer, asks for a new amount

The advantage of this convention is that should the numbering change, and step 2 be come step 3, renumbering the extension handling steps is a lot simpler

In the straight prose style, it's essential to either indent or begin a new paragraph for action steps The Rational Unified Process template includes a designated heading level specifically for the extension condition, with the corresponding action steps detailed beneath this heading.

In the extension-handling scenario fragment, you may encounter a new branching condition, which could indicate a failure If you are following the indentation writing style outlined in this book, just indent again and proceed with naming the condition and writing the scenario as previously demonstrated.

As your indentation and numbering system grows increasingly complex, you may find it necessary to separate the extension for a different use case Many individuals have shared that this typically occurs around the third level of indentation.

Here is an example, taken from Use Case 22, Register a Loss, on page 75.

6a Clerk decides to exit without completing minimum information:

6a1 System warns Clerk it cannot exit and ﬁnalize the form without date, name or policy number, or adjuster name provided.

6a1a Clerk chooses to continue entering loss.

6a1b Clerk saves as “intermediate” report and exits.

6a1c Clerk insists on exiting without entering minimum information:

System discards any intermediate saved versions and exits.

In this instance, the author chose not to assign a number to the final line, opting instead for a concise piece of text to enhance readability, as the extension was already perceived as cluttered.

The high cost associated with developing a new use case often leads individuals to postpone separating an extension into its own distinct use case It appears that the consensus is to maintain a certain level of indentation before considering a breakout, suggesting that this approach is deemed most practical.

Creating a New Use Case from an Extension

To create a new sub-use case from an existing extension, identify the primary actor's goal and assign a name to this use case that reflects its purpose Designate it at the appropriate level, likely as a sub-function Then, open a new use case template and populate it with relevant details extracted from the original calling use case.

Use Case 32, Manage Reports, on page 146 illustrates this It once contained a step that said

User can Save or Print report at any time.

It had a set of extensions describing the various alternatives and failure situations,but they kept growing: unnamed report, preexisting name (do or don’t overwrite), user

Indent Condition Handling

Exercises

8.1 Brainstorm and list the things that can go wrong during operation of an ATM.

8.2 Brainstorm and list the things that can go wrong with the ﬁrst user-goal use case for the PAF Extension Handling system (described in Exercise 4.4 on page 60).

8.3 Write the “Withdraw Cash” use case, containing failure handling, using if statements Write it again, this time using scenario extensions Compare the two.

8.4 Find a requirements ﬁle written in a different form from the one used with use cases How does it capture the failure conditions? What do you prefer about each way of working, and can you capitalize on those observations?

8.5 Write the full use case using the PAF system, ﬁlling out the failure repair steps (PAF is described in Exercise 4.4 on page 60).

Technology and Data Variations 111

Extensions highlight the differences in system functionalities, yet it's essential to acknowledge that "there are several different ways this can be done." While the core outcome remains consistent, the methods employed may differ due to variations in technology or specific data capture requirements These distinctions should be documented in the Technology & Data Variations List, rather than in the Extensions section.

Your system must credit a customer for returned goods You write this action step:

7 Repay customer for returned goods.

The customer can be paid by check, by electronic funds transfer, or by a credit against the next purchase Thus, you add

7a Repay by check, EFTS, or credit against future purchases.

You are specifying a new ATM Technology has advanced to the point that customers can be identiﬁed by bank card, eye scan, or ﬁngerprints You write:

2 User identiﬁes him/herself, bank, and account #.

112 Chapter 9 Technology and Data Variations

2a Use magnetic bank card, eye scan, or ﬁngerprints.

Each variation in your use case represents a distinct extension that may lead to lower-level use cases, which might not be documented These variations significantly affect both your costs and work plans, making it essential to capture and monitor them It's important to utilize the technology and data variations list correctly, as it should only include variations without any action steps or conditions.

The technology and data variations list is seen in Use Case 13, Serialize Access to a Resource, on page 46.

To effectively utilize UML use case diagrams, start by creating a generic base use case that outlines the fundamental concept without detailing the process Then, develop specialized use cases for each variation, which will specify the steps involved in executing the use case For further clarification on UML notation, refer to Appendix A, and see Figure 9.1 for an illustrative example.

Figure 9.1 Technology variations using specialization in UML

Repay customer for returned goods

Linking Use Cases 113

Sub Use Cases

An action step can be defined as a straightforward task or a reference to another use case For instance, when a user saves a report without any annotations or emphasis, it represents a basic, atomic action.

The "Save a Report" use case (UC 35) is straightforward and easily understood, even by casual readers When an action is underlined or italicized, it signifies that another related use case is being referenced, which elaborates on the initial action This method of writing use cases enhances clarity and allows for seamless connections between them, making it efficient in both learning and description.

In UML terminology, an additional use case is introduced, and it's observed that novice writers and casual readers prefer to describe one use case as referencing or invoking another Ultimately, the choice of terminology is a matter of personal preference.

Extension Use Cases

On occasion, you need a different linkage between use cases, one closely matching the extension mechanism Consider this example:

Wapp is an innovative word processing program designed to prioritize typing, allowing users to seamlessly engage in their writing without distractions While typing is the primary focus, users have the flexibility to adjust the zoom factor, change font sizes, run spell checks, and perform various other tasks without interrupting their workflow This approach ensures that the typing experience remains unaffected by any additional document modifications, promoting a smooth and efficient writing process.

To foster innovation, it's essential for various software development teams to generate new service ideas without the need to revise the foundational use case for each addition This approach allows for seamless expansion of the requirements document, ensuring a smooth and efficient development process.

The characteristics of such a situation are as follows:

U There is a main activity, which can be interrupted.

U The main activity can be interrupted in a number of ways, and is not in control of the interruptions.

Unlike a traditional main menu that allows users to select from various system services, our example illustrates a scenario where the primary activity is interrupted by another task, rather than being controlled by user choices.

To avoid maintenance issues, the base use case should not explicitly list all interrupting use cases This approach prevents complications, as any addition of a new interrupting use case requires editing the base use case, which can lead to potential corruption or the need for versioning and review.

To create an extension use case, follow the same mechanism as for scenario extensions, but ensure it can function independently This new use case begins with a condition that refers to a situation in the base use case where this condition may arise Incorporate this information into the Trigger section of the template for clarity and coherence.

The Wapp word processor is depicted in a UML diagram (Figure 10.1), showcasing its functionality A unique connector style, known as a hook, is utilized to illustrate how one use case extends or connects to another For further details, please refer to the Appendix.

Figure 10.1 UML diagram of extension use cases

Trigger: User opens the application

1 User opens a document to edit

2 User enters and modifies text

User saves document and exits application

Trigger: Anytime in Edit a Document that the document is open and the user selects to run the spell checker

Trigger: Anytime in Edit a Document that the cursor is in a word and the user selects to run the thesaurus

Use Case: Change Document Template

Trigger: Anytime in Edit a Document that the document is open and the user selects this function

When to Use Extension Use Cases

Create extension use cases only when you need to, because they are harder for people to understand and maintain Two situations call for their use.

In scenarios where users engage with multiple asynchronous or interruptive services, it is crucial that these services do not interfere with the primary use case Typically, these services are developed by various teams and are delivered as packaged software solutions, such as word processors.

The other situation is when you are writing additions to a locked requirements document As Susan Lilly of S.R.A wrote me,

In an iterative project with multiple drops, once you have established baselined requirements for a specific drop, you can enhance a baselined use case by adding new functionalities in subsequent drops without altering the original use case.

When the base use case is not secured, the extension becomes vulnerable Modifications to the base use case may adversely affect the conditions outlined in the extending use case, necessitating caution in such scenarios Exercise 10.2 provides an opportunity to explore these types of extension use cases.

Alan Williams proposed a valuable principle to determine if a use case should invoke a sub use case or if the secondary use case should extend the primary one.

When the trigger pertains to elements that the base use case manages, meaning it is aware of the timing, location, and rationale for implementing the second use case, the base use case will incorporate, invoke, or reference the latter accordingly.

When the trigger pertains to elements managed by the second use case, which understands the context and rationale for its execution, it effectively extends the base use case.

In use case scenarios, when a base use case invokes a second use case, it specifies the name and context of its execution, while the referenced use case remains unaware of the base use case's identity Conversely, when a second use case extends the base use case, the base use case does not recognize the extending use case, which independently identifies the base use case it interrupts and defines the conditions for its execution.

Exercises

10.1 Find a condition in a user-goal use case for the PAF system (described in Excercise 4.4) that requires a sub use case to be broken out Write that sub use case and link to it from your user-goal use case attending to both its success and its failure.

10.2 Consider the ATM situation in which you are not at your home bank but are a guest at another bank Write the sub use case for a bank-to-bank withdrawal request, and link it with your previous use case(s) about withdrawing money Do this in two ways: as a sub use case that your base use case references and as an extension use case Discuss with a colleague which you prefer and why.

Use Case Formats 119

Formats to Choose From

Most of the examples in this book are in my preferred style, which is fully dressed:

• One column of text (not a table)

• A numbering convention in the extensions section that involves combinations of digits and letters (e.g., 2a, 2al, 2a2, and so on)

The most effective alternatives to the one-column, numbered-step format are the casual form, the two-column style, and the Rational Unified Process template Despite this variety, teams consistently prefer the one-column format when presented with different styles This widely adopted template has been implemented by project teams globally in various tools such as Lotus Notes, DOORS, Word, and Access.

Use Case 24 fm Fully Dressed Use Case Template

Context of Use:

Scope: Level:

Primary Actor:

Stakeholders and Interests:

Precondition:

Minimal Guarantees:

Success Guarantees:

Trigger:

:

In contrast to the fully dressed use case, a casual example from Grady Booch's draft manuscript illustrates a simplified approach This version includes the primary actor, scope, and level, creating a comprehensive example while still incorporating the necessary extensions.

Use Case 25 Actually Login (Casual Version)

When users log in, they must provide a username and password The system checks if a user with that username exists and verifies that the password matches Once authenticated, users gain access to all relevant commands associated with their account.

Users identified as administrators gain access to all submitter and administrator commands Conversely, if the username is invalid or the password does not match, access is denied.

While some individuals prefer presenting scenario steps in a table format, I believe that the table lines can detract from the written content Nonetheless, many still opt for this tabular style, as exemplified by Table 11.1, which showcases the template effectively.

Table 11.1 One-Column Table Format of a Use Case

USE CASE #

Context of Use

Scope

Level

Primary Actor

Preconditions

Minimal Guarantees

Success Guarantees

Trigger

1

Rebecca Wirfs-Brock introduced the concept of a conversation, characterized by a two-column format that displays the primary actor's actions on the left and the system's responses on the right This approach is primarily utilized in the design phase of user interfaces, often providing detailed insights into user interactions.

Using a two-column table format for writing a use case can lead to clarity in presentation, but it often results in lengthy documents that may exceed three pages, as illustrated in Use Case 36, Research a Solution—Before, on page 194 Consequently, revisions are typically necessary to condense the content into a more manageable length.

9 steps at appropriate goal levels, the writing is so simple and clear that people no longer ﬁnd the need for the columns.

Constantine and Lockwood adopt the conversation format when capturing user interface requirements in their essential use cases, as described in Software for Use

(1999) The difference is that in an essential use case, all of the user movements (interface detail) are omitted, so the result is very short, exactly as described.

Using a two-column format to document behavioral requirements presents a challenge, as it lacks a designated space for supporting actors While adding a third column for these actors is a possibility, it is rarely proposed or implemented This oversight occurs because discussions and key use cases primarily focus on user interface requirements rather than the comprehensive behavioral requirements of the system.

Despite various considerations, the two-column format remains appealing to many individuals Feel free to experiment with this layout, and explore the work of Wirfs-Brock, as well as Constantine and Lockwood, who are utilizing it effectively For reference, Table 11.2 illustrates a scenario fragment presented in the two-column style.

Detects that the order number matches the winning number of the month.

Registers the user and order number as this month's winner.

Sends an e-mail to the sales manager.

Congratulates the customer and gives her instructions on how to collect the prize.

The Rational Unified Process (RUP) employs a template akin to the fully dressed template, where the numbering of steps is optional Alternate flows are designated with their own headings, enhancing clarity This book effectively utilizes the template, which, despite its somewhat cluttered appearance due to heading numbers, remains visually appealing and easy to navigate.

Rational Software Corporation provided a use case for illustration, typically accompanied by a use case diagram and additional artifacts The use case is straightforward and easy to understand, utilizing both simple paragraphs and numbered steps for clarity While graphical icons were added to the title for consistency with other examples in the book, no additional fields were included in the template itself For further reference, see Use Case 32, Manage Reports, on page 146, which also employs the RUP template.

Use Case 26 Register for Courses

1 Use Case Name: Register for Courses

Students can register for courses in the current semester using the Course Catalog System, which lists all available offerings During the add/drop period at the start of the semester, students have the flexibility to modify or delete their course selections.

The main actor of this use case is the Student The Course Catalog System is an actor within the use case.

The use case begins when the Student selects the “maintain schedule” activity from the Main Form [ Refer to user-interface prototype for screen layout and ﬁelds ]

2.1.1.1 The Student selects “create schedule.”

2.1.1.2 The system displays a blank schedule form [Refer to user- interface prototype for screen layout and to the domain model for required ﬁelds]

2.1.1.3 The system retrieves a list of available course offerings from the Course Catalog System [How is this selected and displayed? Text? Drop-down lists?]

2.1.1.4 The Student selects 4 primary course offerings and 2 alternate course offerings from the list of available offerings Once the selections are complete the Student selects “submit.” [Deﬁne “primary course offerings” and “alternative course offerings” in project glossary Must exactly 4 and 2 selections be made? Or “up to 4 .,” etc.]

2.1.1.5 The Add Course Offering subﬂow is performed at this step for each selected course offering

2.1.1.6 The System saves the schedule [When is the master schedule updated? Immediately? Nightly (batch)?]

2.2.1.1 The Student selects “modify schedule.”

2.2.1.2 The system retrieves and displays the Student's current schedule (e.g., the schedule for the current semester) [Is this only available for the current semester?]

2.2.1.3 The system retrieves a list of all the course offerings available for the current semester from the Course Catalog Sys- tem The system displays the list to the Student

2.2.1.4 The Student can then modify the course selections by deleting and adding new courses The Student selects the

Students can choose from a selection of 125 available courses to add to their schedule They also have the option to remove any existing course offerings After making the desired edits, students simply need to click "submit" to finalize their changes.

2.2.1.5 The Add Course Offering subﬂow is performed at this step for each selected course offering

2.2.1.6 The system saves the schedule

2.2.2.1 The Student selects the Delete Schedule activity

2.2.2.2 The system retrieves and displays the Student’s current schedule

2.2.2.4 The system prompts the Student to verify the deletion

2.2.2.5 The Student veriﬁes the deletion

2.2.2.6 The system deletes the schedule [At what point are the student slots freed up?]

Students have the option to save their schedule at any time by clicking “save,” which preserves their current selections without officially enrolling in any courses The chosen course offerings will be marked as “selected” in the saved schedule.

Forces Affecting Use Case Writing Styles

During the 1998 OOPSLA conference, a group of 12 seasoned use case writers and educators convened to address prevalent challenges and misunderstandings surrounding use cases Organized by Paul Bramble, the workshop focused on the various factors influencing the diverse approaches to writing use cases If you find yourself confused by the multitude of use case applications, rest assured that the participants shared similar sentiments.

When faced with various challenges, it may be necessary to adapt your approach to writing use cases Embrace patience and tolerance as you tailor your use cases to meet your specific needs Despite these challenges, there remains a clear method for crafting readable and effective use cases.

Forces Affecting Use Case Writing Styles 129

When introducing new use cases, many face the common challenge of resistance due to the phrase, "We've always done it this other way." This sentiment reflects a reluctance to change established practices, highlighting the importance of addressing such concerns to foster innovation and adaptability Recognizing that this struggle is widespread can provide reassurance and motivate teams to explore new approaches while respecting traditional methods.

With multiple cultures, you may ﬁnd

There is prejudice across teams.

There are different work cultures, and people in them simply “do things differently.” The people writing the use cases use a different vocabulary than the people who read them.

Understanding is different at different times and places and among different people. You might choose to shift the recommended writing style based on:

How much you know now

• About use cases in general

Where in the life cycle you know it.

Whether you need to establish content, or cost.

Whether you need the breadth view or the depth view now.

• The presence of clandestine analysis or creeping analysis

• People tend to stress the things they know

• Scheduling versus depth of knowledge versus domain knowledge

What Viewpoint you are after:

The customer is a reader, the use case consumer, happy with a high-level description. The corporate/IT person is a writer, or an implementer, interested in a detailed description.

Various stakeholders may seek to express differing perspectives on use cases related to multiple service groups, debating whether to develop a comprehensive model or a partial one.

Are there different readers involved? If so, who are they?

Every team comprises individuals with varying levels of experience in use cases, where newcomers quickly evolve into proficient writers While seasoned professionals often utilize shortcuts, newcomers seek clear guidance and consistent instructions to enhance their skills.

Formality: Perhaps the leader, or perhaps departmental methodology, dictates a for mal (or informal) writing style, despite any experience or lack thereof

The extent of coverage in a project is influenced by the team's composition, writing abilities, communication skills, and the balance between addressing the entire issue and effectively conveying information to the audience.

Coverage may vary based on

The subject matter experts (they may focus narrowly)

Whether or not the business people know what they want

The decision to work along a common model

The geographic dispersion of the group

The need for consistency of content can conflict with uncertainty or inconsistency in customer requirements:

Use Case complexity involves the following factors:

Describing the full problem domain

Simplifying the view of a system

Forces Affecting Use Case Writing Styles 131

The desire to add technical details (especially when the problem is difﬁcult)

The following factors inﬂuence system complexity:

Analysis paralysis (the complexity of the system overwhelms the analyst)

Simplicity of the user system

Embedded system (it must be error resistant)

The need is to resolve customer conﬂict, but ambiguity masks that conﬂict.

Completeness can be hampered by the following factors:

Requirements are incomplete for the engineering.

The writers don’t have access to users (users are not your customers).

Goals versus Tasks—What to Accomplish versus How to Accomplish It

Users often specify requirements rather than usage.

Context can conﬂict with usage.

Activities and tasks describe what is happening in a system, not why it is happening.

Time is required to write good use cases, but project time is critical Management must buy in to a writing project.

Other factors that affect use case writing are:

The need to partition the requirements for subsequent analysis

Unconstrained design versus level of design to do.

Abstract versus concrete use cases

This comprehensive list serves as a valuable guide for determining the appropriate level of formality in your writing, deciding when to prioritize immediate tasks versus future ones, and balancing the quantity of content with the structure of your writing It also helps you navigate the trade-off between breadth and precision before delving into more detailed exploration.

Standards for Five Project Types

In the context of the project, it's essential to determine the standards we will adopt, which hinges on individual skills, roles, and current objectives Reflect on your own capabilities and goals, and compare them to the previously outlined forces to guide your decision-making process.

In this section, I nominate writing standards for ﬁve particular situations You will notice that the basic choice in each is between casual and fully dressed The ﬁve situations are

1 Eliciting requirements, even if use cases will not be used at all in the ﬁnal requirements document.

3 Drafting or sizing system requirements.

4 Writing functional requirements on a short, high-pressure project.

5 Writing detailed functional requirements at the start of an increment, on a longer or larger project

It is advisable to utilize these standards in their original form; however, after careful evaluation, you may choose to adapt them to better fit your corporate requirements or current circumstances, in line with the principles outlined in the book.

MyCo is set to develop Acura, a new system designed to replace the outdated BSSO This approach emphasizes the importance of using specific names rather than generic terms like corporation and system.

Standards for Five Project Types 133

Use Case 27 Elicitation Template—Oble a New Biscum

Context: The quibquig needs to oble a new biscum once a dorstyp gets nagled (text about the goal in operational context)

Primary Actor: A quibquig (or whoever the primary actor is)

Stakeholders and Interests: Qubquig, MyCo, (whomever and whatever is appropriate).

Preconditions: What must be true before this use case can be triggered

Triggers: The quibquig selects the obling function (whatever it may be).

A paragraph of stuffstuff describing the quibquig successfully obling a biscum with Acura actors do this, that, and the other.

Another paragraph of stuffstuff describing conditions and alternate paths in trying to oble the biscum or failing actors do this, that, and the other.

Frequency of Occurrence: Yay many times a day

Open Issues: a good thing to ﬁll in at this point

Utilize this template to effectively uncover requirements, as highlighted in Steve Adolph’s “Discovering Requirements in New Territory.” Remember that requirements can be expressed in various formats beyond use cases The key is to swiftly navigate through the use cases, collaboratively drafting them during an engaging work session.

The template is casual Keep the stakeholders and interests in the template to re- mind everyone about their requirements, but don't include system guarantees.

Your use cases typically function as black boxes, primarily focusing on user goals While it's acceptable to create higher-level use cases for context, it's advisable to avoid delving into lower-level details frequently.

Use Case 28 Business Process Template—Symp a Carstromming

Context: Text about the goal in operational context

Primary Actor: Whoever the primary actor is

Stakeholders and Interests: Whomever and whatever is appropriate

Minimal Guarantees: Whatever they are

Success Guarantees: Whatever they are

Preconditions: What must be true before this use case can be triggered

Triggers: Whatever it may be

Open Issues: a good thing to ﬁll in at this point

This template is designed for redesigning business processes to accommodate new software, targeting senior line staff, department managers, and executives To enhance readability, focus on clear language and minimize technical data Number the steps for better sequencing and ensure failure handling is described in the extensions, as it highlights crucial business rules The primary use cases will be black-box, illustrating the company's interactions with external partners, serving as benchmarks for measuring business processes or providing context for white-box use cases, which involve systems like MyCo.

Operations illustrate how an organization functions, showcasing the collaboration of individuals and departments to fulfill its objectives This involves utilizing goal levels that range from cloud to sea level For this example, I have chosen a kite-level summary goal to demonstrate the template effectively.

Standards for Five Project Types 135

Use Case 29 Sizing Template—Burble the Tramling

Context: Put here preconditions or conditions of normal usage.

Put here a few sentences describing the actors successfully freeing the necessary fadnap in the main success scenario

Put here a few sentences mentioning some of the alternate paths and the handling

Frequency of Occurrence: How often

Open Issues: always a good idea to mark

This template assists in drafting system requirements to estimate the size and shape of the system You can later elaborate on these requirements for a more comprehensive specification If your project aligns with certain criteria, you may opt to design directly from the informal use cases, as discussed in "The Use Case Briefs" and the importance of understanding potential mistakes.

The template adopts a casual tone, suitable for initial stages of medium precision work, applicable to either a system or a business context Goals can vary in scope, encompassing subfunctions, as the project's complexity is largely influenced by the use cases of these subfunctions For instance, the example of Acura and user goals illustrates this concept Refer to Use Case 25, "Actually Login (Casual Version)," on page 120 for further details.

For a Short, High-Pressure Project

Use Case 30 High-Pressure Template: Kree a Ranfath

A paragraph of text describing the actors achieving success in the main success scenario

A paragraph of text mentioning all the alternate paths and the handling

When facing tight deadlines and limited resources for a project, utilize this simplified template for written requirements to streamline the process Focus on capturing essential elements such as preconditions, guarantees, and extensions without the need for extensive documentation Prioritize enhancing internal communication within the project team to mitigate potential errors, as highlighted in Reminder 19: Know the Cost of Mistakes on page 223.

Use Case 31 Use Case Name—Nathorize a Permion

Utilize this template to gather behavioral requirements through comprehensive use cases, especially for significant projects, fixed-price bids, or geographically dispersed teams It is particularly useful at the beginning of an increment to refine and assess previously drafted sizing use cases, or simply as part of your organizational culture.

The system under design may be anything, as may the actors and goals Again, I used Acura and user-goal level in the sample template.

Conclusion

Use case formats convey similar fundamental information, and the guidelines in this book are applicable to all of them Instead of worrying about the specific format for your project, choose one that is comfortable for both writers and readers.

Exercise

11.1 Rewrite the following use case, getting rid of the if statements and using goal phrases at the appropriate levels and alternate scenarios or extensions.

Perform clean spark plugs service

Conditions: Plugs are dirty or customer asks for service.

3 Cover fender with protective materials.

5 If plugs are cracked or worn out, replace them.

7 Clean gap in each plug.

11 Connect ignition wires to appropriate plugs.

13 If ok, go to step 15.

14 If not ok, take designated steps

16 Clean any grease from car.

Scaling Up to Many Use Cases 143

U You have named all the primary actors and all the user goals with respect to the system.

U You have captured all trigger conditions to the system either as use case triggers or as extension conditions.

U You have written all the user-goal use cases, along with the summary and subfunction use cases needed to support them.

U Each use case is written clearly enough that – The sponsors agree that they will be able to tell whether or not it is actually delivered.

– The users agree that it is what they want or can accept as the system’s behavior. – The developers agree that they can actually develop that functionality.

U The sponsors agree that the use case set covers all they want (for now).

Identifying all primary actors and their user goals is crucial for defining the system's objectives Since there are no external benchmarks to validate this information, it relies solely on the insights of those who will use the system Consequently, it's essential to revisit and brainstorm the list multiple times to ensure completeness and accuracy.

All trigger conditions are crucial for fine-tuning system boundaries, requiring the system to respond to each one In various use cases, specific triggering events manifest as use case triggers, such as when a user inserts a card into a slot, a customer calls to modify their insurance policy, or a user opts to install software.

142 Chapter 12 When Are We Done? upgrade Others are taken care of in the scenario extensions: User hits cancel button, System detects power drop, and so forth.

To effectively reexamine system triggers, it is essential to identify all elements with a life cycle and thoroughly review these lifecycles Focus on identifying events that lead to changes in the state of each element throughout its life cycle.

Summary use cases provide context for user-goal use cases, addressing the common question of how these use cases interconnect Each use case is organized within a higher-level use case, culminating in a single root use case While the root use case serves primarily as a table of contents without a detailed narrative, it offers new readers a valuable starting point to navigate and access all use cases within the system.

Subfunction use cases support user-goal use cases They are needed only if called from several other use cases or to isolate a complicated piece of behavior.

The use cases must be mutually agreed upon by both sponsors and usage experts, ensuring they accurately reflect their needs Additionally, developers must confirm that they can create a system based on these specifications This collaborative agreement presents a significant challenge in the requirements writing process.

The notion of “being done” suggests that all use cases should be completed before design tasks commence, but this is a misconception Different project teams adopt varied strategies based on their needs; some draft all use cases upfront for fixed-price contracts, while others may only outline actors and user goals, postponing detailed use case development until necessary Some teams create use cases for specific work increments, delaying further requirement discussions until later stages, and others write use cases just before beginning a new work phase Each approach has its merits and advocates, highlighting the flexibility required in project management.

CRUD and Parameterized Use Cases 145

CRUD Use Cases

So far there is no consensus on how to organize all those little use cases of the sort

The operations of creating, retrieving, updating, and deleting a Frizzle are collectively known as CRUD use cases, which stem from essential database functions The central question arises: do these operations fall under a singular overarching use case called Manage Frizzles, or should they be considered distinct processes?

While distinct goals may require different individuals and security levels, their separation can lead to a cluttered use case set, potentially tripling the number of items that need tracking.

Opinions vary on managing CRUD use cases, with Susan Lilly of S.R.A supporting the separation of these functions to enhance security tracking for primary actors Conversely, I prefer to begin with a single use case, "Manage Frizzles," to minimize complexity If the content becomes too intricate, I then isolate that component, as detailed in the subsection "Creating a New Use Case from an Extension" on page 109.

I track user access to system data and functions using separate worksheets Neither way is wrong, and I have not seen enough evidence to form a rule one way or the other

John Colaizzi and Allen Maxwell from Empower IT developed a use case that initially began with two separate approaches but ultimately merged into a comprehensive Manage use case They later created a distinct Save sub use case to address the complexity involved Their work illustrates how they adapted their personal writing styles within a structured template, utilizing the Rational Unified Process framework to systematically number the steps and extensions.

* Used with permission from the authors.

146 Chapter 14 CRUD and Parameterized Use Cases

This Use Case outlines the processes involved in Creating, Saving, Deleting, Printing, Exiting, and Displaying Reports It operates at a low level of detail and relies on additional use cases to achieve its objectives, which are detailed in the "Special Requirements" section of the documentation.

File System: typical PC ﬁle system or network ﬁle system with access by user (Secondary)

User selects operations explicitly using the Explorer interface.

1.3 Flow of Events 1.3.1 Basic Flow —Open, Edit, Print, Save, and Exit report a User selects Report by clicking report in Explorer and selects open (open also triggered by double-clicking on report in the Ex- plorer). b System displays report to screen. c User sets report layout, etc., using use case Specify Report Specs. System displays altered report. d Steps c and d repeat until user is satisﬁed. e User Exits report using use case Exit Report. f User can Save or Print report at any time after step c using use case Save Report or the Print Report Alternative Flow listed below.

1.3.2.1 Create New Report a User selects “Create New Report” from Explorer by right clicking and selecting option from pop-up menu. System creates new report with default name and sets report status for name as “unset,” status as “modiﬁed.” b Use case ﬂow continues with Basic Flow at step b. 1.3.2.2 Delete Report a User selects Report by clicking report in Explorer and selects Delete. b System opens report (or makes it current if it is already open) and requests validation from user for deleting report. c Report is closed and resources cleaned up. d System removes report entry from report list and report data is removed from storage medium.

1.3.2.3 Print Report a User selects Report by clicking report in Explorer and selects Print, OR user selects print option of current report (a report being edited/displayed in Basic Flow of this use case). b User selects printer to send report to and printing options speciﬁc to printer (print dialog, etc., controlled by operating system), OR user selects to Print Report to File c System loads report and formats System sends report job to operating system or prints report to designated report ﬁle System closes report.

1.3.2.4 Copy Report a User selects Report by clicking report in Explorer and selects Copy. b System prompts for new report name and validates that name doesn’t exist yet. c System repeats b until user enters a valid (nonexistent) name, opts to save over existing report, or cancels copy operation altogether. d System saves report with designated name as a new report e If copy is replacing an existing report, existing report is removed.

1.3.2.5 Rename Report a User selects Report by clicking report in Explorer and selects Rename. b User enters new name, system validates that name is valid (not the same as it was previously, doesn’t exist already, valid characters, etc.) c System repeats step b until valid name accepted or user cancels use case operation with “cancel” selection. d System updates Report List with new name for Selected Report.

The platform type must be known for control of the report display operations and other UI considerations.

A data element exists on the machine and has been selected as the current element.

148 Chapter 14 CRUD and Parameterized Use Cases

1.3.5.1 Success Postcondition(s) [note: this is the Success Guarantee]

The system is currently awaiting user interaction, and the report may either be displayed or the user may have closed it All requested changes have been saved, a hard copy has been generated, and the report list has been updated accordingly.

1.3.5.2 Failure Postcondition(s) [note: this is the Minimal Guarantee]

System waiting for user The following lists some state possibilities:

This Use Case describes the Save Report process This use case is called from the use case Manage Reports and from the use case Exit Report.

File System: Typical PC ﬁle system or network ﬁle system with access by user (Secondary)

User selects operations through tasks in the Manage Reports use case or Exit Report use case (which is included in Manage Reports use case) to call this use case.

1.3.1 Basic Flow—Save New Report a Use case begins when user selects Save Report b System detects that report name status is “not set” and prompts for new report name User chooses report name; system validates that the report name doesn’t exist in Report List yet Adds entry to Report List. c User cancels save operation Use case ends. d System updates Report List with Report information System creates unique report file name if not already set, and saves report specs to file system. e Report is set as “unmodified” and name status set to “set.” f Use Case ends with report displayed.

1.3.2.1 Alternative Subﬂow—Report name exists—overwrite a System ﬁnds name in list, prompts user for overwrite

User elects to overwrite System uses existing report ﬁle- name and Report List entry Use case continues with step d of Basic Flow.

1.3.2.2 Alternative Subﬂow—Report name exists—cancel a System ﬁnds name in list, prompts user for overwrite

User elects to cancel Use case ends with report displayed.

1.3.2.3 Alternative Flow—Save Report As a User selects Save Report As b User enters new report name, system checks for exist- ence of name in Report List Name does not exist yet

System ﬁnds name in list, prompts user for overwrite

User elects NOT to overwrite Use case continues at step b. c Use case continues with step d of Basic Flow.

1.3.2.4 Alternative Subﬂow—Report name exists—overwrite a System ﬁnds name in list, prompts user for overwrite

User elects to overwrite System uses existing report ﬁle- name and Report List entry Use case continues with step d of Basic Flow.

1.3.2.5 Alternative Subﬂow—Report name exists—cancel a System ﬁnds name in list, prompts user for overwrite

User elects to cancel Use case ends with report displayed.

1.3.2.6 Alternative Flow—Save Existing Report a User Selects Save Report for Current Report (where Cur- rent Report has been saved before and exists in the Re- port List). b System locates entry in Report List, updates List information as needed, saves report specs to report ﬁle. c Report is set as “unmodiﬁed.” d Use Case ends with report displayed.

A data element exists on the machine and has been selected as the

A report is currently displayed and set as the “Current Report.”

1.3.5.1 Success Postcondition(s) [note: this is the Success Guarantee]

System waiting for user interaction Report loaded and displayed Report List is updated with report name, etc., as

150 Chapter 14 CRUD and Parameterized Use Cases required by speciﬁc Save operation Report status is “un- modiﬁed.” Report Name Status is “Set.”

1.3.5.2 Failure Postcondition(s) [note: this is the Minimal Guarantee]

Report status is “modiﬁed.” Report name status same as at start of use case.

Report list still valid (Report list cleaned up when save fails as necessary).

Business Process Modeling 153

Modeling versus Designing

The statement “We are using use cases for business process reengineering” may mean any of the following:

“We use them to document the old process before we redesign it.”

“We use them to create outer behavioral requirements for the design to meet.”

“We use them to document the new process after it is redesigned.”

All of these are valid and interesting I ask you to understand which one you intend

When discussing use cases, I prefer the term business process modeling or documentation rather than business process reengineering or design, as use cases solely document processes without altering them Designers innovate during the design phase, while use cases do not dictate their methods Each documentation level establishes behavioral requirements that subsequent design levels must fulfill, leading to the assertion that "this design meets these behavioral requirements."

Introducing new technology can significantly transform business processes Companies have the option to realign their operations by focusing on core business functions, adapting processes to incorporate new technology, or directly integrating technology while simultaneously developing processes Each of these approaches can be effective in achieving successful integration.

Work from the Core Business

In a top-down approach, the first step is to clearly define the organization's core business, as outlined in Hammer's "Reengineering the Corporation" (1984) This process ultimately leads to a comprehensive understanding of the organization's fundamental operations and objectives.

The stakeholders in the organization’s behavior The external primary actors whose goals you propose that the organization satisfy The triggering events that the organization must respond to

The services the business offers, with the success outcomes for the stakeholders

Understanding how your organization will operate is crucial, as it establishes the boundary conditions for its behavior This foundational information also aligns with the essential elements of a use case, including identifying stakeholders and their interests, defining primary actors and their goals, and establishing success guarantees.

The context for the business process design can be documented using business black-box use cases with the company or organization as the system under design (Figure 15.1).

To optimize current technology, organizations must innovate resource groupings and processes, utilizing computer systems as active memories and communication channels The concept of reengineering the corporation illustrates how various inventive actions can lead to diverse business models and their effectiveness Ultimately, this results in a new organizational design that enhances operational efficiency.

The process of re-invention is documented through white-box use cases, illustrating the interactions between individuals, departments, and potentially computers, to showcase the organization's externally visible behavior.

The fully developed white-box use cases must show the organization’s handling of all failure and exceptional conditions, just as any complete set of use cases or any

Modeling versus Designing 155 complete business process model must You may choose to name the technology in the use cases or not as suits your purpose.

Work from Business Process to Technology

At this intermediate stage, the focus shifts from questioning the organization's core purpose to defining how new technology will integrate into the business You may have identified specific technologies, such as new software applications or mobile devices, and it is essential to establish clear boundary conditions for the development of these technological innovations.

You will write white-box business use cases that document the proposed new business processes without mentioning the new technology (Figure 15.3) Mentioning the

Figure 15.1 Core business black box

Figure 15.2 New business design in white box

In the context of business process modeling, utilizing new technology is as unsuitable as outlining a user interface within a system use case For further illustration, refer to Use Case 21, which details the process of handling a claim.

In essence, computers can be likened to baskets of paper exchanged between individuals Your team's objective is to explore how active conduits, such as full-sized computers or a network of mobile devices and radios, can enhance this process Designers now have a clear understanding of the processes their invention must support Following the invention phase, they will create black-box system use cases that illustrate how the new system integrates with existing technology-free business use cases These use cases will serve as the foundational requirements for the system design.

While the concept appears appealing, it demands significant financial and time investment Given the rapid pace of technological advancement and the accompanying pressures, there often isn't enough time to implement this approach effectively Frequently, I have observed that industry experts, who possess in-depth knowledge of their field, are crucial in navigating these challenges.

Figure 15.3 New business design in white box (again)

Figure 15.4 New business process in black-box system use cases

By effectively linking business and system use cases, professionals can visualize new business process models mentally, resulting in significant time and cost savings This approach facilitates an innovative working method, which will be elaborated on in the following section.

Work from Technology to Business Process

To enhance your organization's technology and work habits, gather a team of experienced usage experts, ensuring that you have two representatives from each department impacted by the system.

During negotiations with technology experts, anticipate their recommendations for system capabilities that can enhance your processes It's important to be ready for them to suggest more than your development team can realistically implement, as pushing technological boundaries is essential for innovation.

Usage experts will create system black-box use cases focused on how the system supports primary actors in achieving their business goals, without referencing the user interface These use cases will include critical and often overlooked business rules in their extension sections To ensure accuracy, experts may consult with colleagues to clarify specific aspects of system behavior Additionally, they will produce summary-level and business use cases that illustrate the context and progression of goals over time.

A streamlined business process documentation will be created as a standard component of the system requirements phase Subject matter experts will conceptualize the new process while discussing how the actors and the new system should function in different scenarios This approach has proven to be highly effective.

U Use Case 3, Register Arrival of a Box, on page 6, illustrates how system behavior documentation can end up describing a fragment of the business process, complete with exceptional conditions.

U Use Case 21, Handle a Claim (Systems), on page 73, is a summary (kite-level) use case that shows the business process context for the system.

The Missing Requirements 161

Precision in Data Requirements

Collecting data requirements is subject to the same directive to manage energy with

“precision” as is every other work product (Section 1.5, Manage Your Energy) I ﬁnd it useful to divide the data requirements into three levels of precision:

U Field lists or data descriptions

In our documentation, we utilize information nicknames, such as "Clerk collects customer information" or "Clerk collects customer’s name, address, and phone number." These nicknames are strategically chosen to streamline the requirements gathering process, ensuring that use cases remain concise and easier to read Expanding on these descriptions could complicate the requirements and make them more vulnerable to changes in data needs, as multiple use cases may reference the same information nicknames.

To effectively manage data requirements, it is essential to delineate them from the use case and connect them to the pertinent field list This connection can be achieved through hyperlinks in various tools or by utilizing a requirements number in tools that facilitate cross-referencing of numbered elements.

When creating field lists, requirements writers must clarify the meanings of each information nickname, such as whether a customer's name includes first and last names or additional components It's essential to specify the necessary details for addresses, considering the diverse formats used globally This is an opportunity for writers to enhance data descriptions with greater precision, which can be done concurrently with drafting use cases or afterward in collaboration with the user interface designer.

There are many strategies for dealing with the second level of precision I’ll name two and you can consult Software for Use (Constantine and Lockwood, 1999) and

GUIs with Glue (Hohmann, in press) for others, or you may have experience in this area yourself.

To effectively manage customer information, create a distinct entry for each nicknamed item in your tool Under the customer name, include three fields: first name, middle name, and last name This initial setup allows for gradual enhancement of the entry, incorporating detailed field information and checks to ensure comprehensive data accuracy over time.

The second strategy emphasizes the importance of grouping name, address, and phone number together in a single use case step, indicating their significance for display and entry This approach aids user interface designers in creating a subscreen or field cluster that accommodates the simultaneous appearance of these data points Consequently, a single entry is established for "name, address, and phone number," outlining the necessary fields for each category without delving into further details.

The distinction between the two strategies lies in how information is organized; the second strategy involves grouping related information into clusters on each field list page Instead of expanding within a single entry, it creates separate entries for each field, enhancing precision and clarity.

As your project progresses and the team gains deeper insights into the data, anticipate changes in the second level of data precision Different team members may define the second and third levels of precision, so it's beneficial to maintain a distinction between the second level of data precision and its specific use case.

When designing databases, programmers and database designers must address key questions regarding field specifications, such as the maximum character length for customer names and any restrictions on the date of loss These considerations involve defining field types, lengths, and validation checks to ensure data integrity.

Some project teams put these items into a requirements chapter called Data Require- ments or External Data Formats Some, who use a hyperlinked medium or database,

In Chapter 16, "The Missing Requirements," it is suggested to categorize certain data into distinct entries labeled as Field Definitions, while other user interface data details should be integrated directly into the user interface requirements and design document Regardless of the approach taken, it is important to keep this distinction in mind.

U You need to expand the ﬁeld details and checks to the third level of precision.

U The use case is not the place to do that expansion.

U The use case should link to that expansion.

U The ﬁeld details are likely to change over time, independently from the use case details.

Cross-linking from Use Cases to Other Requirements

Data formats are not included in the use case itself; instead, the use case identifies the data requirements, allowing for hyperlinks to detailed data descriptions While complex business rules may not seamlessly integrate into the use case narrative, they can be linked to relevant entries This hub-and-spoke linking approach positions use cases as the focal point of the requirements document, encompassing both functional and nonfunctional requirements.

Figure 16.1 Recap of Figure 1.1, “Hub-and-Spoke” model of requirements

Cross-linking from Use Cases to Other Requirements 165

When creating use cases, it's important to avoid forcing requirements that don't align with their structure, as they are primarily designed to capture interactions between actors For certain operations, such as tape merges or compilers, traditional use cases may fall short, and alternative methods like algebraic or tabular representations are more effective for accurately describing these requirements.

Only a fraction of the requirements set is suited to the use case form It just so happens that the interaction part is central and connects many other requirements.

Use Cases in the Overall Process

Use Cases in Project Organization

Use cases provide management with insights into the functional benefits delivered to users Each use case is titled to reflect a specific goal that a primary actor can achieve with the system Additionally, the body of each use case outlines the system's requirements and the features it will offer.

Organize by Use Case Titles

In the initial stages of project planning, it is essential to construct a table that includes use case and primary actor names in the first two columns The third column should capture the business sponsors' assessment of the priority or value associated with each use case Meanwhile, the fourth column should reflect the development team's estimation of the complexity or difficulty in delivering each function This approach naturally builds upon the actor-goal list methodology.

Kent Beck's "Planning Game," outlined in "Extreme Programming Explained: Embrace Change" (1999), presents a unique approach where developers estimate development costs while business sponsors prioritize use cases This method allows sponsors to adjust priorities based on work estimates, although they cannot alter the estimates themselves To implement this strategy effectively, consider filling out your planning table in two distinct passes.

You can enhance the planning table by including additional columns to indicate the development priority of each use case, the initial release version, or the responsible development team (refer to Table 17.1).

You can view and manipulate this table with ease over the course of the project.

168 Chapter 17 Use Cases in the Overall Process

Over time, you will complete the estimates for each use case, assign them to teams, and track the work per use case per release

The following true story illustrates how utilizing a planning table can effectively gauge, estimate, prioritize, and minimize the potential working set of use cases, leading to significant benefits in project management and efficiency.

U The use case list clearly shows the system’s value to the business.

U The list of names provides a structure for working with development priority and timeframe.

Any Check on requests Top Large job in general case

Authorizor Change authorizations High Simple 2 3

Buyer Change vendor contacts Medium Simple 3 4

Requestor Initiate an request Top Medium 1 5

Mark request delivered Low Simple 4 8

Refuse delivered goods Low Unknown 4 9

Approver Complete request for submission

Buyer Complete request for ordering

Initiate PO with vendor Top Complex 1 12

Alert of nondelivery Low Medium 4 13

Authorizer Validate Approver’s signature

Receiver Register delivery Top Medium 1 15

Use Cases In Project Organization 169

Handle Use Cases Crossing Releases

It would be soothing to say that a tidy set of complete use cases maps to each release, except that it doesn’t

A use case such as Order Product calls out all sorts of special handling, which will be delivered over time A typical staging strategy is

U Deliver the simple case in release 1.

U Add high-risk handling in release 2.

U Put preferred customer handling in release 3.

Either you write one use case and deliver a fraction of it in each release, or you write three use cases Each way will work, and each way will hurt.

Some teams opt to divide use cases into distinct units for complete delivery in releases, such as Order Product (Base Case), Order Product (High-Risk Handling), and Order Product (Preferred Customer Addition) They may either repeat the use case body with new elements in italics or create extension use cases for each subsequent unit While this approach simplifies tracking, it results in three times the number of use cases to manage, and crafting the additional use cases can be challenging.

Many users prefer use cases to be easily readable, accepting that they will be released in segments Key sections are often highlighted in yellow or italics, indicating which parts will be available first, such as “the highlighted portions of Use Case 5.” While this approach is common in various projects and functions adequately, it lacks the tidiness that some may desire.

A developer was tasked with identifying business processes for upcoming software releases, resulting in an extensive 7-page actor-goal list After collaborating with the executive sponsor, they condensed it to half a page by estimating value, complexity, and triggers The developer then crafted a main success scenario for the prioritized processes and further refined the list to half a page of system-level goals Equipped with this focused information, she visited branch offices to gather insights.

After her return, she outlined specific business steps that would greatly benefit branch office employees Together with the sponsor, they pinpointed four key use cases to focus on for development in the upcoming six months.

A balanced approach to software development involves starting with a comprehensive multi-release use case, followed by isolating the functionality for each increment During subsequent increments, previously delivered parts are presented in plain text, while new features are highlighted in bold This method allows for a controlled expansion of use cases, maintaining clarity for teams managing multiple functionalities Although there are 80 initial use cases, the perception of managing these increases with each increment It’s essential to choose a strategy, recognizing that each has its limitations All methods assume the organization employs incremental staging and delivery, typically within four-month cycles, which has become a best practice in modern software projects, as outlined in "Surviving Object Oriented Projects" (1998) and the article “VW Staging.”

In software development, it's common for a use case to be delivered in multiple phases, yet each phase must encompass a complete scenario A use case outlines the user's objectives and details the various scenarios required to achieve them To ensure the application provides usable functionality, each delivery must implement several of these scenarios comprehensively.

Effective planning and design are essential for creating functional collections that meet end-user needs, ensuring that all scenarios align with defined use cases Functional testers play a critical role in verifying the compatibility of these use cases Successful deployment can only occur when all use case threads are fully operational and usable.

This seems trivial, but overlooking it can hurt, as the preceding story illustrates

U A Short, True Story about Integration

The test and integration manager of a large project raised concerns about the risks associated with incremental development, as the writing team was delivering the application in isolated "features" rather than cohesive use cases This approach hindered his team's ability to test the components effectively, as they lacked a coherent narrative to support them, resulting in a disorganized collection of mechanisms In response, project leaders revamped the project plan to ensure that each increment contributed to a usable storyline, enhancing both testing and integration processes.

Use Cases to Task or Feature Lists 171

Use Cases to Task or Feature Lists

Effective communication within development teams streamlines the process of translating use cases into design tasks, preventing potential project management challenges that arise from misalignment and outdated mappings.

The following email from a colleague illustrates this.

In the past two weeks, we met with [the client] to discuss requirements and build a collaborative relationship with the developers We focused on use cases, which we believed were 90%–95% accurate for design and development, instilling confidence in our approach A scope document was created to outline the included and excluded features, resembling the sample scope section provided Initially brief, the document was expanded in response to requests for a more traditional requirements format, while still aiming to maintain minimal detail.

During our initial meeting with the developers, they focused on reviewing the "requirements" outlined in the scope document, which we recognized lacked the necessary detail for our intended use case focus To address this, we dedicated three days to creating a revised scope document, which I refer to as "spoon feeding" the use cases to the team Our goal was to influence the development culture and facilitate a shift towards use-case-based requirements We organized the document by labeling each use case as a feature set, with corresponding steps from the use case documents listed as individual features beneath their respective headings.

We encountered a challenge that necessitated our dual maintenance approach: the original text from the scenarios lacked clarity and effectiveness as standalone features Despite our efforts to replicate the text, we frequently found ourselves rephrasing or adding context to enhance its coherence and relevance.

Designers prefer to begin with numbered requirements or feature lists to guide their work In some instances, detailed requirements documents are created first, followed by the development of use cases, although this approach may seem counterintuitive.

There exists a fundamental tension between the system's behavior outlined in use cases and the specific design tasks assigned to individual designers Designers often focus on isolated features, such as the Undo mechanism, Transaction Logging, or the Search Screen Framework, which may be embedded within a single use case or interconnected across multiple ones This fragmentation makes it challenging for designers to articulate the broader implications of their work.

In Chapter 17, we explore the significance of use cases within the overall process, highlighting that stakeholders often struggle to articulate their contributions effectively Instead of detailing the entire system's flow, they typically reference specific components, such as stating, "I’m working on the Search Screen part of Use Case 5." This illustrates the challenges in communicating roles and responsibilities in use case development.

Sponsors of the software are eager to witness the application operating at its full potential, providing significant value to users, as the individual design tasks lack inherent interest.

Maintaining synchronization between the use case document and the design task list can be a tedious and exhausting process, often requiring repetitive efforts throughout the project I believe this is an unnecessary task to undertake In my experience managing projects with teams of up to 50 people, I have not needed to decompose use cases into detailed line items This success may stem from my emphasis on personal communication and collaboration, as well as the positive cultures of the teams I've worked with We have effectively managed to mentally break down tasks or use simple methods, like a yellow highlighter, to identify key items for scheduling without incurring significant overhead.

An alternative approach involves creating two separate documents and diligently maintaining their updates If you opt for this strategy, divide the use case text into manageable segments that can be assigned to individual developers or teams Each segment will represent a specific program feature, mechanism, or design task, which should be assigned, tracked, and marked as completed The comprehensive estimate for software development is derived from the total of all design task estimates, while project tracking entails recording the initiation and completion of each task.

The following is an example of converting a use case to a work list.

Use Case 34 Capture Trade-In

Goal in Context: The Shopper has a shopping cart containing products and wants to add a trade-in to see how it will affect costs.

Preconditions: The shopping cart must contain product(s).

Success Guarantees: The trade-in has been valued, added to the shopping cart, and has reduced the cost of the items contained in the shopping cart.

Minimal Guarantee: If not ﬁnalized, the trade-in is not captured or added to the shopping cart.

Primary Actor: Shopper (any arbitrary web surfer)

Trigger: Shopper selects to capture a trade-in.

1 Shopper selects to capture a trade-in.

2 System determines the value of trade-in by presenting information to the Shop- per and asking a series of questions to determine the value of the trade-in The series of questions and information presented depend on the answers the Shop- per gives along the way The path of questions and information is predetermined, in order to highlight probable business practices around trade-ins.

Use Cases to Task or Feature Lists 173

3 The system logs the navigation and trade-in information along the way.

4 Shopper reviews the trade-in summary and value, considers it.

5 Shopper adds it to the shopping cart.

6 System adds to the shopping cart the trade-in and the navigation information.

7 System presents a view of the shopping cart with all the products and trade-ins contained in it, as well as re-calculating the total cost taking into consideration the trade-in(s).

Shopper repeats the above steps as many times as desired to capture and value different trade-ins, adding them to the shopping cart as desired.

2a At any time prior to adding the trade-in to the cart, the shopper can go back and modify any previous answer.

5a Shopper decides not to add the trade-in to the shopping cart: System retains the navigation information for later.

When shopping, customers often want their trade-in value to be applied to a specific item in their cart This allows shoppers to designate which product they wish to benefit from the trade-in, enhancing their overall purchasing experience.

Table 17.2 is the generated work list.

Table 17.2 Work List for Capture Trade-In

EC10 Capture Trade-In Must have 1.0

EC10.1 Provide the ability for the shopper to enter a trade- in into the shopping cart.

EC10.2 Provide the ability to present and navigate through generated UI forms (based on templates) to gather the shopper’s trade-in information to determine its value

EC10.3 enables users to access an external trade-in system to assess the value of their items The shopper's relevant trade-in details are transmitted to this external platform, which evaluates the trade-in and provides its value along with key characteristics.

EC10.4 Provide the ability for the shopper to be presented a trade-in summary, including its value.

Use Cases to Design

Use cases outline the essential black-box behavioral requirements that the design must fulfill, specifying what the system should accomplish while allowing designers the creative freedom necessary for effective design It is the responsibility of designers to apply their expertise to create a design that satisfies these outlined requirements, ensuring that the focus remains solely on achieving the specified outcomes without imposing additional constraints.

There are several things to say about transitioning from use cases to design, some good and some bad The bad is that

U The design doesn’t cluster by use case.

U Blindly following the use case structure leads to functional decomposition designs (this is really of concern to object-oriented and component design teams). The good is that

U Some design techniques can take advantage of all the scenarios

U Use cases name the concepts needed in domain modeling

Let’s look at the bad ﬁrst.

EC10.5 enables shoppers to easily add or remove trade-ins while shopping When a trade-in is added to the cart, it can be linked to a specific product or applied to all items in the cart, enhancing the shopping experience.

EC10.6 Provide the ability to recalculate the total cost of the contents of the shopping cart, taking into consideration the trade-in(s).

EC10.7 Provide the ability to edit an existing trade-in by re- turning to the trade-in question/answer process for editing.

EC10.8 Provide the ability to delete an existing trade-in from the shopping cart and recalculate the total cost.

EC10.9 Provide the ability to log any trade-in information or steps based on preconﬁgured triggers.

Table 17.2 Work List for Capture Trade-In (Continued)

Design tasks do not neatly align with specific use cases, as they often produce business objects or behavioral mechanisms applicable across multiple scenarios Information from a later release's use case can significantly impact design tasks completed in earlier releases, necessitating adjustments to those designs when new insights are discovered.

To effectively manage design tasks, one approach is to have designers thoroughly review all use cases for relevant information This method is most feasible for smaller projects, but if successfully implemented, it can provide a significant advantage.

The second approach involves analyzing all use cases to identify high-risk items and key functions that significantly impact the design The team then develops a design centered around these critical functions, with the expectation that other functions will not disrupt the overall design too much.

The preferred approach acknowledges that software evolves throughout its lifecycle, allowing for flexibility in design The team strategically plans each release while understanding that new requirements are likely to emerge within the next year, necessitating adjustments.

Transitioning to this alternative might create discomfort for team members accustomed to database design practices, where adding new fields to a table and reoptimizing the database can be costly In such environments, designers are encouraged to identify all potential attributes beforehand, leading to software releases that may be considered only partially complete, ranging from 20% to 100% of the total attributes.

In contemporary incremental development environments, adding an attribute to a class or table is a simple and cost-effective task This allows developers to define only the essential components of a class or entity as needed Consequently, classes and components are considered "complete" only in relation to a specific set of functions, which evolves as new functionalities are introduced.

Be prepared for this discussion Unless there are extremely strong economic pen- alties, I suggest that your team work to the model of “completeness with respect to a named function set.”

A team lead expressed frustration over not being able to fully complete classes beyond the 20% mark, despite the delivered application meeting all customer requirements This issue highlighted a misunderstanding between the database design culture and the incremental development culture being used on the project, which took considerable time to resolve.

Functional decomposition is beneficial for structured decomposition techniques in use cases, but if you are engaging in object-oriented design, it's essential to consider different approaches.

A Special Note to Object-Oriented Designers

Functional decomposition effectively communicates behavioral requirements through clear and understandable writing, allowing for a structured hierarchy of system behaviors While beneficial for outlining requirements, this approach may not be ideal for software design, as co-encapsulating data and behavior aids in the maintenance and evolution of software However, there is no evidence that functional decomposition serves well for gathering or conveying requirements, and in my experience, a function-based structure proves to be more effective.

Requirements gathering is enhanced through functional decomposition, while software design gains from the componentization of data and behavior Designers must analyze use cases, engage in thoughtful discussion, and develop effective abstractions, as this responsibility lies with them, not the users.

A common pitfall for inexperienced designers is the tendency to create classes that directly reflect the functional decomposition outlined in the requirements document, translating each use case into a class, object, or component However, seasoned professionals in object-oriented design caution against this approach, as it often leads to suboptimal outcomes.

Creating a separate class for user-goal use cases can be justified, as it represents a complete transaction with clear commit and rollback semantics, making it suitable for encapsulation In contrast, subfunction use cases typically lack these qualities, as they often consist of partial mechanisms that belong to multiple classes.

The risk for object-oriented (OO) designers arises when they focus solely on modeling the domain without considering the necessary functions, leading to a neglect of functional requirements Use cases are essential as they guide domain modelers on which aspects of the domain are relevant, preventing wasted effort on irrelevant modeling They establish boundary conditions that ensure effective domain modeling For further insights, refer to “An Open Letter to Newcomers to OO” (http://members.aol.com/humansandt/papers/oonewcomers.htm).

Use Cases to UI Design

Larry Constantine and Lucy Lockwood, in Software for Use, and Luke Hohmann, in

GUIs with Glue, have written better than I can about designing the user interface.

However, during use case writing, most project teams ask, “How do we transition from UI-free use cases to actual UI design?”

Certain staff members are tasked with creating a user-friendly interface, leveraging their skills to develop a design that adheres to specified use cases By carefully analyzing these use cases, they aim to create a presentation that simplifies user interactions while maintaining the essential steps outlined The resulting UI design will meet the requirements established in the use cases and will undergo review by both users and programmers to ensure its effectiveness.

Use case writers can benefit from envisioning themselves as entering data into a screen or completing a paper form, which helps identify necessary information and any sequencing constraints It is important to interpret these forms as reflections of the usage experts' perspectives on their tasks rather than as definitive requirements.

Although the requirements document should not detail the UI design, including samples of the UI can enhance its clarity and effectiveness.

* Read the original article by K Beck and W Cunningham, “A Laboratory for Object-Oriented

Thinking,” ACM SIGPLAN, or the book by R Wirfs-Brock, B Wilkerson, and L Wiener,

Designing Object-Oriented Software Online, visit http://c2.com/cgi/wiki?CrcCards or http:// members.aol.com/humansandt/papers/crc.htm.

Chapter 17 discusses how use cases enhance the overall process by providing design information that improves the readability of requirements documents This information presents both textual and visual representations of the system's behavior, offering a clearer understanding of its functionalities.

The UI design has three levels of precision, low, medium, and high:

The low-precision user interface description utilizes a screen-navigation diagram, represented as a finite state machine or statechart Each state corresponds to a specific screen that users will encounter, while the finite state machine illustrates the user events that trigger transitions between these screens.

A medium-precision description serves as a visual representation or a scaled-down snapshot of the screen, effectively summarizing the design It is recommended to position this illustration at the conclusion of the use case, allowing readers to both view and comprehend the nominated design seamlessly.

• The high-precision description lists all the field types, lengths, and validation checks of each screen and does not belong in the requirements document at all.

Use Cases to Test Cases

Use cases offer a straightforward functional test description for systems, making them highly appealing to test groups This approach often marks the first instance where testers encounter such user-friendly materials, particularly when these test suites are provided during the requirements phase The experience is further enhanced when testers have the opportunity to contribute to the creation of the use cases.

In a formal development environment, the testing team is responsible for breaking down use cases into numbered test cases and creating a comprehensive plan that outlines the specific settings necessary to activate various paths They will develop all relevant test cases to establish and evaluate these settings, while also addressing the different data configurations required for thorough testing of data combinations Additionally, the team will design performance and load tests, which are essential tasks that extend beyond the initial use cases.

The test team should consider the provided tables 17.3 and 17.4 by Pete McBreen as a standard reference These tables outline the use case followed by a corresponding set of acceptance tests It is essential for your test team to adapt this example to align with their specific work practices.

Notice Pete's use of stakeholders and interests to help identify the test cases and how his test cases contain specific test values

Use Case 35 S Order Goods, Generate Invoice (Testing Example) ^ti

Context: Customer places order for goods, an invoice is generated and sent out with the ordered items

In case of failure, goods will not be allocated to the Customer, Customer account information will remain unchanged, and the transaction attempt will have been logged

Use Cases to Test Cases 179

Goods will have been allocated to the Customer.

Invoice will have been created (Customer Invoicing Rule applies)

Picking list will have been sent to distribution

1 Customer selects items and quantities

2 System allocates required quantities to customer

3 System obtains authenticated invoicing authorization.

5 System send picking instructions to distribution

2a Insufﬁcient stock to meet required quantity for item:

2b Out of stock on item:

3a Customer is bad credit risk (link to acceptance test case for this exception).

Every extension requires at least one test case, but to achieve comprehensive coverage, additional test cases are necessary to evaluate data values The primary success scenario test case should be prioritized, as it effectively demonstrates the system's performance under high-volume conditions This test case can often be developed prior to fully understanding all extension conditions and recovery paths.

Table 17.3 Main Success Scenario Tests (Good Credit Risk)

Initial System State/Inputs Customer Pete, a Good Credit risk, orders one of

Quantity on hand for Item #1 is 10.

Expected System State/ Outputs Quantity on hand for Item #1 is 9.

Invoice is generated for Customer Pete for one of Item #1 at a price of $10.00.

Use Case Briefs and Extreme Programming 187

While the advice to "write the intent of the actor and use a nickname for the data" may seem sufficient, it is inadequate for developers Programmers and user interface designers require detailed information about the address, including its specific fields, field lengths, and validation rules for components like addresses, zip codes, and phone numbers This crucial information should be included in the requirements documentation, rather than being relegated to the use case.

Use cases represent just one aspect of the requirements document, specifically focusing on behavioral requirements They do not encompass critical elements such as performance criteria, business rules, user interface design, data descriptions, finite state machine behavior, or prioritization.

System developers often question the location of requirements, noting that while use cases shouldn't include them, they must be documented elsewhere Relevant information can be linked to each use case as associated data, which may encompass essential details necessary for understanding the context and functionality of the system.

U Open issuesDifferent projects adjust this list to contain whatever they consider important.

A simple spreadsheet or table effectively captures essential information, making it a popular choice for many at the project's outset to gain an overview of use case details Typically, users place the use case name in the leftmost column and populate the subsequent columns with relevant data.

That still leaves out the section the programmers need just as much as they need the behavioral requirements—the data requirements, including ﬁeld checks to perform.

Collecting data requirements is subject to the same directive to manage energy with

“precision” as is every other work product (Section 1.5, Manage Your Energy) I ﬁnd it useful to divide the data requirements into three levels of precision:

U Field lists or data descriptions

The Clerk gathers essential customer information, including names, addresses, and phone numbers, which will be detailed further in subsequent sections Utilizing appropriate nicknames for this information streamlines the requirements gathering process, preventing unnecessary complexity that could make use cases longer and more vulnerable to changes Additionally, many use cases are likely to reference the same information nicknames, enhancing consistency and clarity across the documentation.

To effectively manage data requirements, it is essential to detail them based on the use case and connect them to the corresponding field list This can be achieved through hyperlinks in various tools or by using a requirements number in systems that allow for cross-referencing of numbered items.

When developing field lists, requirements writers must clarify the specifics of each information nickname, such as whether a customer's name includes two or more parts Additionally, they need to define the necessary components for addresses, considering the diverse formats used globally This process allows writers to enhance data descriptions with greater precision, which can be integrated alongside use case development or in collaboration with user interface designers.

There are many strategies for dealing with the second level of precision I’ll name two and you can consult Software for Use (Constantine and Lockwood, 1999) and

GUIs with Glue (Hohmann, in press) for others, or you may have experience in this area yourself.

To enhance organization, create a distinct entry in your tool for each nicknamed item Under the customer name, include three fields: first name, middle name, and last name Gradually, you can refine this entry by adding detailed field information and checks, ensuring it encompasses all relevant details as outlined in the subsequent section on field details and checks.

The second strategy emphasizes the importance of grouping name, address, and phone number together in a single use case step, indicating their significance for user interaction This insight aids user interface designers in creating a dedicated subscreen or field cluster to accommodate this trio of information consistently across various locations Consequently, a unified entry for "name, address, and phone number" is established, outlining the necessary fields for each component without delving into further details.

The key distinction between the two strategies lies in the organization of information; the second approach involves grouping related data into clusters on each field list page Instead of elaborating on a single entry, this method creates distinct entries for each field, allowing for greater precision and clarity.

As your project progresses and the team gains insights into the data specifics, anticipate changes in the second level of precision It's common for various individuals to define the second and third levels of data precision differently Keeping the second level of data precision distinct from the use case can be beneficial.

When designing databases, programmers and database designers must address critical questions regarding field specifications, such as the maximum length for customer names and the restrictions applicable to the date of loss These considerations encompass field types, field lengths, and necessary field checks to ensure data integrity.

Some project teams put these items into a requirements chapter called Data Require- ments or External Data Formats Some, who use a hyperlinked medium or database,

In Chapter 16, titled "The Missing Requirements," it's essential to organize information effectively by classifying certain entries under Field Definitions, while incorporating user interface data directly into the user interface requirements and design document This approach ensures clarity and coherence in the documentation process.

U You need to expand the ﬁeld details and checks to the third level of precision.

U The use case is not the place to do that expansion.

U The use case should link to that expansion.

U The ﬁeld details are likely to change over time, independently from the use case details.

16.2 CROSS-LINKING FROM USE CASES

Data formats are essential for understanding the needs outlined in use cases, allowing for hyperlinks to detailed data descriptions While complex business rules may not fit seamlessly into the use case narrative, they can still be linked to relevant entries This hub-and-spoke linking approach positions use cases as the focal point of the requirements document, encompassing both functional and nonfunctional requirements.

Figure 16.1 Recap of Figure 1.1, “Hub-and-Spoke” model of requirements

Cross-linking from Use Cases to Other Requirements 165

When creating use cases, it's important to avoid forcing incompatible requirements into this format, as use cases are primarily designed to capture interactions between actors For certain operations, such as tape merges or compiler functionalities, traditional use cases may not be effective; instead, these requirements are more appropriately described using algebraic or tabular methods.

Only a fraction of the requirements set is suited to the use case form It just so happens that the interaction part is central and connects many other requirements.

Mistakes Fixed 189

No System

Before Use Case: Withdraw Cash

1 Customer enters card and PIN.

2 Customer enters “Withdrawal” and amount.

3 Customer takes cash, card, and receipt.

This use case illustrates all the actions taken by the primary actor while neglecting to depict the system's behavior It is surprisingly common for individuals to create use cases in this manner, prompting reviewers to remark, "It appears that the system is not required to perform any actions."

We can sure design that in a hurry.”

The ﬁx is to name all the actors with their actions.

You should be able to write an ATM use case in your sleep by now.

1 Customer runs ATM card through the card reader.

2 ATM reads the bank ID, account number, encrypted PIN from the card, validates the bank ID and account number with the main banking system.

3 Customer enters PIN The ATM validates it against the encrypted PIN read from the card.

4 Customer selects Fast Cash and withdrawal amount, a multiple of $5.

5 ATM notiﬁes main banking system of customer account, amount being withdrawn, and receives back acknowledgment plus the new balance.

6 ATM delivers the cash, card, and a receipt showing the new balance.

No Primary Actor

Here is a fragment of a use case for withdrawing money from an ATM.

2 Collects transaction type as “Withdrawal.”

4 Validates that account has sufﬁcient funds.

This use case focuses solely on the ATM system's functions, neglecting the actions of the primary actor Such a perspective can lead to difficulties in comprehension, verification, and correction Additionally, it often results in the omission of crucial details regarding the actor's behavior, particularly related to the sequence of interactions.

The ﬁx is straightforward: Name every actor and action.

Too Many User Interface Details 191

The same as in Section 19.1.

Too Many User Interface Details

1 System presents ID and Password screen.

2 Customer types ID and password into system, clicks OK.

3 System validates user ID and password, displays Personal Information screen.

4 Customer types in ﬁrst and last names, street address, city, state, zip code, phone number, and clicks “OK.”

5 System validates that user is a known user.

6 System presents available product list.

7 Customer clicks on pictures of items to be purchased, types in quantity next to each, clicks on “Done” when ﬁnished.

8 System validates with the warehouse storage system that sufﬁcient quantity of the requested product is in stock.

One of the most prevalent mistakes in writing requirements documents is over-describing the user interface, which transforms the document into a user manual rather than a clear requirements outline Excessive UI details do not enhance the narrative; instead, they clutter the content and render the requirements less flexible.

The fix is finding a way to describe the intentions of the user without actually nominating a specific solution This sometimes takes a little creative wording.

1 Customer accesses system with ID and password.

3 Customer provides name, address, telephone number.

4 System validates that Customer is a known Customer.

5 Customer selects products and quantity.

Very Low Goal Levels

1 User accesses system with ID and password.

8 System validates that user is a known customer.

9 System opens a connection to warehouse system.

10 System requests current stock levels from warehouse system.

11 Warehouse storage system returns current stock levels.

12 System validates that requested quantity is in stock.

This use case may seem lengthy and tedious, but while we can't fault the detailed description of the user interface, our goal is to condense the content and clarify the key actions taking place.

To effectively merge data items, it is essential to collect each piece separately, focusing on the user's intent to provide personal information This term serves as a broad label for the various data points being gathered However, to enhance clarity, it's beneficial to reference a detailed field list, which will be elaborated on in a different context without impacting the current use case.

Purpose and Content Not Aligned 193

When organizing information, it's often beneficial to consolidate related details into a single step, particularly for steps three through seven However, it's important to recognize that personal information can differ significantly from product selection and quantity While some may prefer to keep these elements together for clarity, others may choose to separate them for better readability Ultimately, the decision depends on personal preference and the specific context, ensuring that the layout remains clear and uncluttered.

To achieve a higher-level understanding of the system's objectives, it's essential to ask, “Why is the system performing these actions?” This inquiry reveals that the system aims to confirm with the warehouse storage system whether there is an adequate quantity of the requested product available This concise articulation of the goal effectively captures the requirements while maintaining clarity.

1 User accesses system with ID and password.

3 User provides personal information (name, address, telephone number), selects product and quantity.

4 System validates that Customer is a known Customer.

Purpose and Content Not Aligned

This is a reminder for you to do Exercise 7.4 at the end of Chapter 7, on page 98, which asks you to repair the faulty LogIn use case.

If you haven’t done it yet, look for these three mistakes:

U Its body does not match the intent described in the name and description In fact, it is at least two use cases rolled together.

U It describes user interface details.

U It uses programming constructs in the text rather than the language of ordinary people.

If you are determined to avoid the work, turn to Appendix B to see the discussion and resolution.

Advanced Example of Too Much UI

FirePond Corporation graciously permitted the use of a before-and-after example The original version spanned eight pages, with six dedicated to the primary success scenario and its alternatives In contrast, the revised version is only a third of the length, retaining the essential information while providing a more flexible user interface.

Read the main success scenario carefully, and ask yourself how you might make this long use case more palatable without sacriﬁcing content Notice, particularly, the

UI design is evident in the text, and while reviewing some extensions can be beneficial, it's not essential to examine them all in detail Although I have eliminated certain extensions, I've retained sufficient content to highlight the challenges associated with managing a lengthy use case.

In the realm of information technology marketing, it's essential to recognize that a shopper's journey involves more than merely selecting a product; they actively engage in researching a solution tailored to their specific situation While I may prefer to rename this use case as "Select a Product," the established title of "Research a Solution" accurately reflects the context in which it was created and will be interpreted, thus remaining unchanged.

Thanks to Dave Scott and Russell Walters of FirePond Corporation.

Use Case 36 Research a Solution—Before

Primary Actor: Shopper—a consumer or agent wanting to research products she may purchase

1 This use case begins when the

Shopper visits the e-commerce web site.

2 System may receive information about the type of Shopper visiting the web site.

3 System will require establishing the identity of the Shopper , Initiate establish identity If the system doesn’t establish the identity here, it must be established prior to saving a solution.

4 The system will provide the Shopper with the following options: Create a new solution, Recall a saved solution.

6 System will present the ﬁrst question to begin determining the Shopper’s needs and interests.

Advanced Example of Too Much UI 195

7 Shopper can repeat adding Prod- uct Selections to shopping cart:

8 While questions exist to determine needs and interest:

10 System will prompt with a varying number and type of questions based on previous answers to determine the Shopper’s needs and interests along with presenting pertinent information such as production information, features & beneﬁts, and comparison information

11 Shopper answers last question 12 At the last question about needs and interest, the system will present product line recommendations and pertinent information such as production information, features & beneﬁts, comparison information, and pricing

13 Shopper will select a product line 14 System will present the ﬁrst question to begin determining the product model needs.

15 While questions exist to determine

17 System will prompt with questions that vary based on previous answers to determine the Shopper’s needs and interests related to product models, along with pertinent information such as production information, features & beneﬁts, comparison information, and pricing

18 Shopper answers last question 19 At the last question about product model needs, the system will present product model recommendations and pertinent information such as production information, features & beneﬁts, comparison information, and pricing

20 Shopper will select a product model.

21 System will determine standard product model options, and then present the ﬁrst question about determining major product options.

22 While questions exist to determine

24 System will prompt with questions that vary based on previous answers to determine the Shopper’s needs and interests related to major product options, along with pertinent information such as production information, features & beneﬁts, comparison information, and pricing.

25 Shopper answers last question 26 At the last question about major product option desires, the system will present the selected model and selected options for Shopper validation.

During the Research Solution process, if the Shopper remains inactive for a set time-out period, the system will notify them of the inactivity and ask if they wish to continue If the Shopper does not respond to this prompt within 30 seconds, the session will conclude; however, if they do respond, they can proceed with the process.

*b At any point during the question/answer sequences, the Shopper can select any question to go back to, modify their answer, and continue through the sequence.

*c At any point after a product recommendation has been presented, the Shopper can view performance calculation information as it pertains to their needs The

27 Shopper reviews their product selection, determines they like it, and chooses to add the product selection to their shopping cart.

28 System will add product selection and storyboard information (navigation and answers) to the shopping cart.

29 The system presents a view of the shopping cart and all of the product selections within it.

30 End of repeating steps of adding to shopping cart.

32 Shopper will request a personal- ized proposal on the items in their shopping cart.

33 System will present the ﬁrst question to begin determining what content should be used in the proposal.

34 While questions exist to determine proposal content:

36 System will prompt with questions that vary based on previous answers to determine the proposal content, along with pertinent information such as production information, features & beneﬁts, comparison information, and pricing

37 Shopper answers the last question 38 At the last question about proposal content, the system will generate and present the proposal.

39 Shopper will review the proposal and choose to print it.

40 System will print the proposal.

41 Shopper will request to save their solution.

42 If the Shopper identity hasn’t been established yet, Initiate Establish Identity

43 System will prompt the user for solution identiﬁcation information.

44 Shopper will enter solution identi-

ﬁcation information and save the solution.

45 System will save the solution and associate with the Shopper

Advanced Example of Too Much UI 197 system will perform the calculation and present the information The Shopper will continue with the Research Solution process from where they left off.

*d At any point during the question/answer sequences, the system may interface with a Parts Inventory System to retrieve part(s) availability and/or a Process &

The planning system efficiently retrieves the build schedule and part availability, allowing for the filtering of product selection information This data enhances the shopper's research experience by displaying real-time availability Key use cases include initiating the retrieval of part availability and the build schedule, ensuring a seamless shopping process.

During the question and answer sequences, the system provides relevant information, including industry-related links The Shopper can select these links, allowing the system to share product-related or solution information to guide them to the best content Once the Shopper completes their visit to the industry website, they return to their previous point, potentially bringing back product requirements for system validation This process initiates the viewing of product information.

*f At any point during the research process, the Shopper may request to be con- tacted: Initialize Request For Contact use case.

During the question-and-answer sequences, the system may identify key market data trigger points, allowing it to capture navigational data, product selections, and inquiries This information will be used for external market analysis.

*h At any predetermined point in the research process, the system may generate a lead providing the solution information captured up to that point Initialize

*i At any point the Shopper can choose to exit the e-commerce application:

When a new solution is developed or an existing one is modified since the last save, the system will alert the Shopper, prompting them to save the updated solution.

*j At any point after a new solution has been created or the current one has been changed, the Shopper can request to save the solution Initiate Save Solution.

1a A Shopper has been visiting a related-product vendor’s web site and has established product requirements The vendor’s web site allows launching to this e- commerce system to further research a solution:

1a1 Shopper launches to e-commerce system with product requirements and possibly identiﬁcation information.

1a2 System receives the product requirements and potentially user identiﬁcation.

1a3 System will validate where the Shopper is in the research process and establish a starting point of questions to continue with the research process.

1a4 Based on established starting point, we may continue at step 5, 12, or 18.

3a Shopper wants to work with a previously saved solution:

3a1 Shopper selects to recall a solution.

3a2 System presents a list of saved solutions for this Shopper

3a3 Shopper selects the solution they wish to recall.

3a4 System recalls the selected solution.

23a Shopper wants to change some of the recommended options:

Reminders for the Use Case Set 215

Reminders for Each Use Case

Reminder 1: A Use Case Is a Prose Essay

Writing use cases is essentially akin to crafting prose essays, presenting similar challenges in effectively conveying ideas As noted by Russell Walters from FirePond Corporation, this process requires careful articulation to ensure clarity and coherence.

The statement highlights a commonly misunderstood issue that serves as a significant revelation for use case writers It suggests that practitioners may struggle to achieve this understanding independently, at least until the release of this book Despite four years of experience with use cases, I initially failed to recognize this as the fundamental problem.

Working alongside you provided valuable insights, particularly when I analyzed the before and after versions of the use case you helped rewrite (Use Case 36 on page 194) It took over four years for me to fully grasp the key issues in crafting effective use cases I hope readers of this book come away with a clear understanding of these fundamental challenges in writing.

Use this reminder to help keep your eyes on the text, not the diagrams, and to be aware of the writing styles you will encounter.

Reminder 2: Make the Use Case Easy to Read

You want your requirements document short, clear, and easy to read

I sometimes feel like an eighth-grade English teacher walking around, saying,

To enhance clarity and engagement, use active verbs in the present tense Focus on the subject of each sentence and ensure it drives the action Clearly state essential requirements without including unnecessary details.

206 Chapter 20 Reminders for Each Use Case

To create a concise and clear requirements document, adopt these habits for writing effective use cases: prioritize brevity, ensure clarity, and enhance readability.

1 Keep matters short and to the point Long use cases make for long requirements, which few people enjoy reading.

Begin by establishing a clear and engaging storyline that starts with a strategic use case at the top From this central point, outline the user goals and develop subfunction-level use cases that branch out, ensuring a coherent flow throughout the narrative.

3 Name the use cases with short verb phrases that announce the goal to be achieved.

4 Start from the trigger and continue until the goal is delivered or abandoned and the system has done any bookkeeping it needs to with respect to the transaction.

5 Write full sentences with active verb phrases that describe the subgoals being completed

6 Make sure the actor and the actor’s intent are visible in each step.

7 Make the failure conditions stand out and their recovery actions are readable Let it be clear what happens next, preferably without having to name step numbers.

8 Put alternative behaviors in the extensions rather than in if statements in the main body.

9 Create extension use cases only under very selected circumstances.

Reminder 3: Just One Sentence Form There is only one form of sentence used in writing action steps in the use case:

U A sentence in the present tense,

U with an active verb in the active voice,

U describing an actor successfully achieving a goal that moves the process forward. Here are examples:

Customer enters card and PIN.

System validates that customer is authorized and has sufﬁcient funds.

PAF intercepts responses from the web site and updates the user’s portfolio. Clerk Finds a Loss using search details for ‘loss.’”

Use this sentence form in business use cases, system use cases, and summary,user, and subfunction use cases, with either the fully dressed or casual template It is

Reminder 5: Who Has the Ball? 207 the same in the main success scenario and in the extension scenario fragments Mas- ter this sentence style.

To avoid confusion between the condition and action steps in an extension, it is beneficial to use a distinct grammatical form Utilizing a sentence fragment or a complete sentence, ideally in the past tense, can enhance clarity Conclude the condition with a colon (:) rather than a period for better readability.

Time-out waiting for PIN entry:

User exited in the middle:

Data submitted is not complete:

Reminder 4: “Include” Sub Use Cases

To achieve your goal naturally, you would typically write a step that references a specific lower-level objective or use case.

Clerk ﬁnds a loss using search details for “loss.”

In UML, the calling use case incorporates the sub use case, a practice so fundamental that it often goes unmentioned However, some writers and educators promote the use of UML's extends and specializes relationships, which can complicate this straightforward approach.

To enhance clarity in writing, it is essential to consistently apply the "includes" relationship between use cases Adhering to this guideline helps reduce confusion for both writers and readers, unlike those who intermingle "includes" with "extends" and "specializes." For more detailed guidance, refer to the section on using extension use cases.

Reminder 5: Who Has the Ball?

Using the passive voice or a system-centric perspective can lead to vague sentences, such as "Credit limit gets entered," which lack clarity about the subject performing the action It's essential to specify who is responsible for the action to enhance understanding and engagement in writing.

From my vantage point high above, I observe a bustling scene below, akin to a vibrant play unfolding in real-time The spotlight shines on Actor 1, who skillfully maneuvers the ball with finesse, weaving through the crowd with agility With a swift kick, they pass to Actor 2, who seamlessly receives the ball and sends it soaring to Actor 3 Each movement is a choreographed dance, showcasing teamwork and strategy, as the players navigate the field with purpose and precision, creating a captivating spectacle for all to witness.

Actor John skillfully navigates the challenging scenes, showcasing his versatility Actor Sarah captivates audiences with her powerful performances, bringing depth to every character Actor Michael consistently delivers compelling dialogue, enhancing the overall narrative Actor Emma effortlessly transitions between emotions, leaving a lasting impression on viewers Actor David commands attention with his dynamic presence, making each moment memorable Actor Lisa masterfully engages with the script, ensuring a seamless flow of the story Actor Tom's dedication to his craft shines through, elevating the film's quality.

208 Chapter 20 Reminders for Each Use Case

Reminder 6: Get the Goal Level Right

U Review Section 5.5, Finding the Right Goal Level, for the full discussion

U Make sure that the use case is correctly labeled with its goal level: summary, user, or subfunction.

Regularly assess your understanding of your goals in relation to "sea level" and determine how far above or below it your current progress stands Remember the criteria for establishing a sea-level goal: it should be conducted by a single individual, in a specific location, and within a timeframe of 2 to 20 minutes.

– The actor can go away happily as soon as it is completed.

– The actor (if an employee) can ask for a raise after doing many of these.

Most use cases consist of three to nine steps in the primary success scenario, with each step's goal level generally positioned slightly below that of the overall use case.

If you have more than nine steps, look for steps to merge in the following places: – Where the same actor has the ball for several steps in a row.

– Where the user’s movements are described These are typically user interface movements, violating Guideline 5, Show the Actor’s Intent, Not the Movements, on page 92.

Reminders for Working on the Use Cases 221

Reminders for the Use Case Set

Reminder 12: An Ever-Unfolding Story

In a development project, the primary use case, often referred to as "Use the ZZZ System," functions as a table of contents that outlines the actors and their overarching goals While it lacks a detailed storyline, this use case provides a valuable starting point for newcomers exploring the system, making it a preferred reference for many users seeking a centralized entry point for their reading.

The primary use case highlights the overarching objectives of the main actors within a corporate information system, typically involving external customers and the marketing department.

The interrelationships of sea-level use cases define the system, with the narrative typically beginning from one of these use cases These outermost use cases evolve into user-goal use cases, where the design scope focuses on the system being developed The process illustrates the interaction between actors and the system, aimed at achieving the user's immediate objectives.

In a sea-level use case, a transition to an underwater (indigo or subfunction) use case occurs when the sub use case is complex or utilized in multiple scenarios Given the high maintenance costs associated with subfunction use cases, they should only be implemented when necessary Typically, subfunction use cases are essential for tasks such as finding a customer or locating a product.

In the realm of indigo use cases, a single instance can evolve into a more complex scenario, highlighting the importance of perceiving the use case set as a continuous narrative This perspective allows for the seamless transition of intricate sections into standalone use cases or the integration of simpler sub-use cases back into their parent cases Essentially, each action step has the potential to develop into an independent use case, as detailed in Section 10.1 on Sub Use Cases.

216 Chapter 21 Reminders for the Use Case Set

Reminder 13: Both Corporate Scope and System Scope

Design scope can often lead to confusion due to varying interpretations of system boundaries It's essential to clearly distinguish between business use cases and system use cases to avoid misunderstandings.

A business use case focuses on the operational aspects of an organization, detailing how an external actor achieves a specific goal related to the business Typically, it does not reference technology, emphasizing the processes and functions that drive the organization's operations.

A system use case focuses on the design scope of a computer system, highlighting how an actor interacts with the technology to achieve a specific goal.

Business use cases are typically presented in a white-box format, detailing interactions among individuals and departments within a company, while system use cases are generally in a black-box format This distinction is important, as business use cases focus on current or future company designs, whereas system use cases aim to establish requirements for new designs Essentially, business use cases provide insights into the internal workings of the business, while system use cases outline the external functionalities of the computer system.

When designing a computer system, it's essential to include both business and system use cases in your documentation The business use case outlines the system's functional context and its role within the organization.

To minimize confusion, clearly label the scope of each use case and consider using graphic icons to differentiate between business and system use cases Additionally, incorporating a visual representation of the system within its containing system in the use case can enhance clarity and understanding.

Reminder 14: Core Values and Variations

Despite the continuous emergence of new use case formats, seasoned writers are increasingly aligning on fundamental format principles The 1999 TOOLS USA conference featured two papers (Firesmith, 1999, and Lilly, 1999) that identified the most common errors in use case writing The mistakes and their solutions highlighted in these papers resonate with essential core values.

Goal-oriented use cases focus on the objectives of primary actors and the subgoals of various participants, including the System under Development (SuD), in reaching those objectives Each sentence highlights the achievement of a specific subgoal.

Reminder 14: Core Values and Variations 217

The article presents a unique perspective by depicting actions from a bird's eye view, illustrating the scene from above rather than an internal viewpoint It emphasizes an observational approach, akin to a play that names its actors, allowing readers to grasp the dynamics of the situation without delving into the inner thoughts or feelings of the characters involved.

To ensure effective communication, it is crucial that use cases and specifications are easily readable If the content is difficult to understand, it fails to fulfill its primary objective Enhancing readability may require compromising on some precision and accuracy, but this can be offset by fostering greater engagement However, sacrificing readability can lead to disengagement, causing your audience to overlook your use cases entirely.

USABLE FOR SEVERAL PURPOSES Use cases are a form of behavioral description that can serve various purposes at various times in a project For example, they have been used to

U Provide black-box functional requirements.

U Provide requirements for an organization’s business process redesign.

U Document an organization’s business process (white box).

U Help elicit requirements from users or stakeholders (to be discarded when the team writes the ﬁnal requirements in some other form).

U Specify the test cases that are to be constructed and run.

U Document the internals of a system (white box).

U Document the behavior of a design or design framework.

Project Planning Using Titles and Briefs

Ellipses and Stick Figures

When illustrating system interactions on a whiteboard, it's common to represent users as stick figures and use ellipses or boxes for the corresponding use cases Each stick figure should be labeled with the actor's title, while the ellipses or boxes are labeled with the titles of the use cases This visual representation conveys the same information as the actor-goal list but offers a different presentation style, effectively serving as a table of contents for the system's functionalities.

So far, all is all ﬁne and normal.

The challenges arise when individuals mistakenly view diagrams as definitive representations of a system's functional requirements This obsession with diagrams can lead to the false belief that they simplify complex tasks, resulting in an overwhelming amount of information being included in the visuals Consequently, there is a hope that text will become unnecessary, which can hinder effective communication and understanding.

A fellow course participant presented a large, complex diagram filled with ellipses and arrows, indicating various relationships like includes, extends, and generalizes However, he struggled to grasp whether his project accurately utilized these relationships, ultimately revealing that the diagram's chaotic nature made it nearly impossible to comprehend the intended functionality of his system.

234 Appendix A Use Cases in UML

A developer proudly demonstrated how he "fixed" the flaw in diagrams that failed to indicate the sequence of sub use cases By adding numerous arrows to illustrate the order of precedence using UML relations, he created an overly complex diagram This resulted in a visual that occupied more space than the equivalent text and was significantly more difficult to comprehend In essence, he could have conveyed a thousand clear words in the space of his one convoluted illustration.

A drawing is a two-dimensional tool designed to enhance cognitive understanding by emphasizing relationships, rather than serving as a substitute for text With this objective in mind, we can examine the specific relationships represented in UML.

In software development, a base use case incorporates an included use case when an action step explicitly references the included use case's name This relationship illustrates the connection between a higher-level use case and its associated lower-level use case The included use case focuses on a more specific goal that supports the broader objective of the base use case.

In action steps, the verb phrase can represent a sub use case; if the goal isn't separated into its own use case, it remains just a step However, if the goal is defined as a distinct use case, the step then references this sub use case or incorporates its behavior, aligning with the terminology of UML 1.3 Previously, before UML 1.3, the term used was "lower-level use case," which is now considered outdated.

In Figure A.1, a dashed arrow indicates the relationship between the higher-level base use case and the included use case, demonstrating that the base use case is aware of the included one.

UML’s Includes Relation

Draw Higher Goals Higher

UML’s Extends Relation

An extension use case enhances a base use case by specifying the base use case and outlining the conditions that allow it to be interrupted The base use case remains unaware of the extending use case, which streamlines the process of adding multiple interrupting use cases without the need for constant updates to the base use case This approach minimizes maintenance challenges and facilitates easier management of use case scenarios.

The extending use case defines specific internal conditions and triggering events within a base use case, allowing behavior to progress until the condition is met At that point, the process transitions to the extending use case and resumes in the base use case once the extending use case is completed Rebecca Wirfs-Brock creatively describes the extending use case as a "patch" on the base use case, a concept familiar to programmers akin to program patches, while others view it as a textual representation of mock programming instructions, similar to a "come-from" statement.

In use case writing, we naturally employ the extension form for extension conditions An extension use case represents these conditions, with the handling separated and developed into an independent use case Essentially, it can be viewed as a scenario extension that has evolved beyond its original use case, warranting its own dedicated space.

The default UML drawing for extends is a dashed arrow (the same as for includes) from extending to base use case, with the phrase “” set alongside it I draw

In UML, understanding the distinction between includes and extends relationships is crucial for accurately modeling use cases Figure A.2 illustrates how an extending use case connects back to the base use case, emphasizing this difference This visual representation aids in grasping the unique functionalities that each relationship brings to the overall system design.

Figure A.2(a) shows the default UML way of drawing extends (the example is from

UML Distilled (Fowler, 1999)) Figure A.2(b) shows the hook connector.

Guideline 14: Draw Extending Use Cases Lower

In a use case diagram, an extension use case typically appears lower than the primary use case it extends Despite this positioning, the extending use case is aware of the base use case, which is why the arrow or hook representing the relationship is drawn upward from the extension to the main use case symbol.

Guideline 15: Use Different Arrow Shapes

UML intentionally leaves the arrow styles connecting use case symbols undefined, allowing for customization by tool vendors and project teams However, this flexibility often leads to the overuse of generic arrows, resulting in diagrams that are difficult to interpret Readers are forced to rely on small text descriptions to understand the relationships, which can hinder comprehension and memory retention To enhance clarity, it is essential to establish distinct arrow styles for the three types of relations in use case diagrams.

U Includes: Use the default, open-headed arrow, as it should be the most frequently used one

U Generalizes: The standard generalizes arrow in UML is the triangle-headed arrow Use that

U Extends allows for the creation of a distinct shape that enhances the understanding of use cases By utilizing a hook that connects to the base use case, this method remains easily recognizable and does not clash with other UML symbols It effectively illustrates the metaphor of an extending use case being linked to the base use case To ensure clarity, it is essential to make the extends connector visually distinct from other connectors in the diagram.

Extension use cases are typically created when multiple asynchronous services can interrupt the main use case, often developed by different teams This scenario frequently arises in the development of shrink-wrapped software packages.

In incrementally staged projects, it is common to lock the requirements document after each delivery When this occurs, you may need to extend a locked use case by adding new functionality.

The concept of "extends" was created to avoid altering the requirements file of existing systems In early telephony systems, as business needs evolved, asynchronous services were frequently introduced The extends relationship allowed new teams to build upon a securely maintained requirements document, enabling them to incorporate new requirements for asynchronous services into the base use case as needed, all without modifying the original system requirements.

Figure A.3 Three interrupting use cases extending a base use case

Check SpellingChange TemplateFind Synonym

Referencing behavior in another use case poses challenges, particularly when line numbers are absent, making it unclear how to identify where the extension behavior begins Conversely, if line numbers are present, any edits to the base use case that alter these numbers can lead to confusion regarding the correct reference points.

Line numbers serve as labels for readability and reference in extension conditions, and while they are typically sequential and numeric, they can be non-numeric and may change over time.

Extension points were created to address existing issues by serving as publicly visible labels within the base use case These labels identify specific moments in the use case's behavior using a nickname, providing clarity and structure to the process.

Publicly visible extension points create a challenge for base use case authors, as they must constantly identify and modify the use case whenever new extension opportunities arise This contradicts the original intent of using extensions, which was to minimize the need for modifications to the base use case.

When addressing common issues in use case extensions, I believe that publicly declared extension points often create more complications than benefits Instead, I recommend providing a textual description of where the extending use case integrates with the base use case, without relying on specific nicknames, as illustrated in the ATM example below.

Use Different Arrow Shapes

UML’s Generalizes Relations

A use case may specialize a more general one (the general use case generalizes the speciﬁc one) The (specializing) child should be of a “similar species” to that of the

According to UML 1.3, a generalization relationship between use cases indicates that the child use case inherits all attributes, behavior sequences, and extension points from the parent use case, while also engaging in all the relationships established by the parent.

A strong test word is "generic," exemplified by phrases like "some kind of." Be mindful when you use expressions such as "The user does some kind of this action," as this indicates a potential for generalization.

Here is a fragment of the Use the ATM use case.

1 Customer enters card and PIN.

2 ATM validates customer’s account and PIN.

3 Customer does a transaction, one of:

Withdraw cash Deposit cash Transfer money Check balance Customer does transactions until selecting to quit.

What is it the customer does in step 3? The generic answer is “a transaction.”

Customers can engage in four types of transactions, highlighting a generalized goal of conducting a transaction While the plain-text version merely enumerates these operations, UML emphasizes the importance of the generalized relationship by utilizing a generalization arrow to illustrate the connections between different use cases.

We have two options for structuring our approach: we can either focus solely on specific operations, as illustrated in Figure A.4(a), or we can develop a general use case for performing a single ATM transaction, which would then include the specific operations as specializations, as depicted in Figure A.4(b).

Use whichever you prefer Working in prose, I don’t create generalized use cases.

Creating a new use case page for the generic goal is unnecessary due to the lack of relevant text However, graphically representing specific transactions is challenging, necessitating the identification and naming of the generalizing goal.

Guideline 16: Draw General Goals Higher

Always draw the general goal higher on the diagram, and point the triangular arrow- head up into the bottom, not the sides Figure A.4 illustrates this.

When integrating actor specialization with use case specialization, caution is essential It is important to avoid scenarios where a specialized actor is paired with a specialized use case For example, while a Sales Clerk can handle various deals, only a Senior Agent possesses the expertise to close high-value transactions, highlighting the need for clear distinctions in roles and capabilities.

In Section 4.2, we discussed the concept of the primary actor, highlighting that a specialized actor can execute all use cases available to a general actor For example, the Sales Clerk functions as a generalized Senior Agent, which may appear counterintuitive to some, yet it is an accurate and official classification.

Closing a significant deal is essentially a specific instance of finalizing a regular transaction According to UML guidelines, a specialized use case can replace a general use case in any context This implies that even an ordinary sales clerk has the capability to close a large deal.

Figure A.4 Drawing Generalizes A set of included use cases is converted into specializations of a generic action

Withdraw Cash Deposit Cash Transfer Funds

Withdraw Cash Deposit Cash Transfer Funds a b

The corrected drawing is shown in Figure A.6 You might look at the drawing and ask: Does closing a small deal really specialize closing a basic deal, or does it extend it?

Engaging with text use cases avoids unnecessary confusion and economic waste, making it a topic worth exploring for those interested.

The challenge with generalized relations in the professional community lies in the lack of consensus on the concepts of subtyping and specializing behavior, including the associated properties and options As use cases represent descriptions of behavior, a standardized understanding of how to specialize them is still absent.

To optimize the use of generalized relations, it's advisable to keep the generalized use case empty, similar to the "Do One Transaction" example This approach allows the specializing use case to encompass all necessary behavior, minimizing concerns to just one specific issue previously mentioned.

Figure A.5 Hazardous generalization—closing a big deal

Figure A.6 Correctly closing a big deal

Close a Small Deal Sales Clerk

Draw General Goals Higher

Subordinate versus Sub Use Cases

In the UML 1.3 specification, two lesser-known relationships between use cases, namely subordinate and superordinate use cases, are described without visual representation or specification in the object constraint language These relationships illustrate how the use cases of various system components collaborate to fulfill the use case of the larger system Interestingly, the components are not depicted; instead, their use cases exist independently in a conceptual space, resembling an anonymous collaboration diagram that requires further elaboration through a detailed collaboration diagram.

A use case detailing a model element is refined into multiple smaller use cases, each outlining a specific service of the original model element Importantly, the structure of the overarching container element remains undisclosed in these use cases, which focus solely on the functionalities provided by the individual elements The subordinate use cases work together to fulfill the objectives of the primary use case, and their collaborative interactions can be illustrated through collaboration diagrams.

The introduction of peculiar relations in the use case specification lacks clarity, and I do not intend to elaborate on them However, I mention this because I use the term "sub use case" in this book, which may prompt questions regarding the relationship between Cockburn's sub use case and the UML subordinate use case.

In this article, I introduce the term "sub use case" to describe a lower-level goal within a higher-level use case, which typically includes the sub use case Previously, I referred to these as "subordinate" and "superordinate," but I have adapted my terminology since UML 1.3 adopted those terms My experience shows that the phrases "calling use case" and "sub use case" are easily understood by both novice writers and readers, making them effective for clear communication.

Drawing Use Case Diagrams

To effectively communicate your ideas through use case diagrams, it's essential to adhere to specific diagramming conventions Avoid overwhelming your readers with a chaotic arrangement of arrows; instead, aim for clarity and simplicity By following Guidelines 13 to 16, which outline the various use case relations, along with two additional drawing guidelines, you can enhance the readability and understanding of your diagrams.

Write Text-Based Use Cases Instead 243

Guideline 17: User Goals in a Context Diagram

In the main context diagram, it is essential to avoid displaying any use cases that fall below the user-goal level, as the diagram's primary objective is to offer context and an organized overview of the system being developed To maintain clarity, any decomposed use cases should be presented on separate pages.

Guideline 18: Supporting Actors on the Right

To enhance clarity in system diagrams, I recommend positioning all primary actors on the left side, while reserving the right side for supporting (secondary) actors This approach minimizes confusion between primary and secondary roles Some individuals choose not to include supporting actors in their diagrams, which enables them to position primary actors on both sides.

A.7 WRITE TEXT-BASED USE CASES INSTEAD

Focusing too much on graphics and complex relationships can drain your energy; instead, prioritize writing clear and concise prose In straightforward writing, the connections between use cases become evident, making it easier to understand the material without getting bogged down by unnecessary complications.

This is a view shared by many use case experts It is somewhat self-serving to re- late the following event, but I wish to emphasize the seriousness of the suggestion.

During a panel discussion at OOPSLA '98, Bruce Anderson from IBM's European Object Technology Practice addressed concerns about scenario explosion and the confusion surrounding the use of "includes" and "extends." He noted that his team does not experience scenario explosion and attributed their clarity to following Alistair's advice: focusing on writing clear text, avoiding the use of "extends," and not relying heavily on diagrams.

Effective text-based use cases eliminate the challenges often faced by those using UML's stick figures, ellipses, and arrows When crafting a narrative, relationships within the use case emerge organically, becoming problematic only if overly scrutinized As consultants gain experience in both text and UML, a consensus is forming around the advantages of narrative-driven use cases.

We could be describing our neighborhood, or the set of electronically connected indus- tries On a smaller scale, we could be designing the bank building and lighting system.

The discussion could revolve around the design of a new bank computer system and ATM, focusing on either the entire system or just the ATM itself It might also involve the development of a new key panel design or a specific Enter key design The fragment does not clarify which particular system or component is being addressed.

Again, we cannot tell from the user story fragment which system we are discussing

Figure B.1 Design scopes for the ATM

246 Appendix B Answers to (Some) Exercises

Recall the pass/fail tests An actor must be able to execute an if statement’s worth of behavior A primary actor has a goal, calling upon a system’s promised services

The customer A primary actor and stakeholder.

The ATM card Not an actor It does not have sufﬁcient behavior (this refers to

"Dead iron filings" cards and "smart cards" with embedded chips serve as data envelopes for ATM transactions, facilitating quick and efficient customer input.

The bank Not an actor for our purposes It is a system containing the ATM.

The front panel Not an actor for our purposes It is a component of the SuD.

The bank owner A stakeholder, probably not a primary actor.

The printer Not an actor for our purposes It is a component of the SuD.

The main bank computer system A secondary actor It might be a primary actor if you can think of a situation in which it initiates a conversation with the ATM.

The role of the bank teller varies based on job assignments, particularly in tasks such as emptying and refilling cash If one identifies the cash refilling task with service staff, the bank teller may not be seen as the primary actor in this scenario However, if the bank teller is recognized as responsible for these duties, they indeed serve as the primary actor in banking operations.

The concept of a bank robber can vary based on design scope and creativity Initially, I struggled to find a meaningful use case for a bank robber beyond merely extending a customer's use case However, the suggestion to "Steal the ATM!" introduced the idea of incorporating a movement detector Depending on how we define the objective, we might create a use case for the robber—whose goal ultimately fails—or simply add more extension conditions to the customer's use case.

The answers depend on which containing system you choose (see Figure B.1).

The ATM Not an actor for our purposes It is a now a component of the SuD.

The customer Still a primary actor and stakeholder.

The ATM card Not an actor, for the same reasons as in Exercise 4.2 (with the same disclaimers).

When analyzing the banking system, consider Figure B.1 If you selected "Bank with people" as the primary system, this represents your System under Discussion (SuD) Conversely, if you opted for "Electronic Banking Network," this may serve as an actor, contingent upon your ability to substantiate a service provided by the Electronic Banking System.

The front panel Not an actor for our purposes It is a component.

The role of the bank owner is influenced by the chosen system and the established service goals Depending on these factors, the bank owner may serve as a component within the bank, thus not being a primary actor, or they may take on a primary role within the bank while likely not being a key player in the Electronic Banking System.

The serviceman A primary actor if a hired outside serviceman, a component if an employee of the bank and you chose the Bank as the SuD.

The printer Not an actor for our purposes It is a component.

The main bank computer system It is now a component of the containing system (either of them).

The bank teller Either a component (of the Bank) or possibly a primary actor of the Electronic Banking System.

The bank robber Same as for Exercise 4.2

U Summary (white): Take Someone out for Dinner, (this is a somewhat con- trived answer in the case of the ATM).

U Summary (white): Use the ATM,

U User goal (blue): Get Money from the ATM,

U Subfunction (black): Find the Enter Button,

The easiest way to ﬁnd the minimal guarantee is to ask, “What would make a stakeholder unhappy?” The stakeholders are the customers, the bank, and the banking oversight agency.

Customers will be dissatisfied if they do not receive their cash, especially if they are charged for a transaction without receiving the expected amount They experience frustration whenever debited more than the cash they obtain Additionally, customers require a detailed log of all transactions to protect themselves against potential fraud.

The bank is concerned about customers receiving more cash than the debited amount, necessitating a detailed transaction log to safeguard against errors during catastrophic failures Additionally, the oversight agency emphasizes the importance of adherence to guidelines, focusing on the generation of a comprehensive log of all transactions.

We provide a minimal assurance that the debited amount matches the dispensed amount, along with a detailed micro-log of the transaction process in the event of a catastrophic failure Additionally, every transaction is thoroughly logged for transparency and accountability.

Supporting Actors on the Right

Write Text-based Use Cases Instead

Focusing excessively on graphics and complex relationships can divert your energy from what truly matters Instead, channel your efforts into crafting clear and concise prose In well-written prose, the connections between use cases become evident, allowing you to see why others may struggle with them.

This is a view shared by many use case experts It is somewhat self-serving to re- late the following event, but I wish to emphasize the seriousness of the suggestion.

During a panel discussion at OOPSLA ’98, Bruce Anderson from IBM's European Object Technology Practice addressed concerns regarding the differences between includes and extends in use cases, as well as the issue of scenario explosion He noted that his team does not experience scenario explosion or confusion, prompting a question about why others struggle with these issues Bruce attributed his team's clarity to following Alistair's advice: focusing on writing clear text, avoiding the use of extends, and not relying heavily on diagrams.

Effective text-based use cases alleviate the challenges often faced by those using UML's stick figures and symbols By crafting a narrative, relationships within the use case emerge organically, becoming problematic only when overly scrutinized As consultants accumulate experience in both text and UML, a consensus grows regarding the advantages of narrative-driven approaches.

We could be describing our neighborhood, or the set of electronically connected indus- tries On a smaller scale, we could be designing the bank building and lighting system.

The discussion could revolve around the design of a new banking computer system, an ATM, a key panel, or even a new Enter key Without additional context, it's unclear which specific system or component is being addressed.

Again, we cannot tell from the user story fragment which system we are discussing

Figure B.1 Design scopes for the ATM

Recall the pass/fail tests An actor must be able to execute an if statement’s worth of behavior A primary actor has a goal, calling upon a system’s promised services

The customer A primary actor and stakeholder.

The ATM card Not an actor It does not have sufﬁcient behavior (this refers to

"Dead iron filings" cards and "smart cards" with embedded chips serve as data envelopes, facilitating quick and efficient transactions for customers at ATMs.

The bank Not an actor for our purposes It is a system containing the ATM.

The front panel Not an actor for our purposes It is a component of the SuD.

The bank owner A stakeholder, probably not a primary actor.

The printer Not an actor for our purposes It is a component of the SuD.

The main bank computer system A secondary actor It might be a primary actor if you can think of a situation in which it initiates a conversation with the ATM.

The role of the bank teller varies based on job assignments, particularly in tasks such as emptying and refilling cash If you identify the refilling responsibility as belonging to service staff, you may not consider the bank teller as a primary actor However, if you recognize that the bank teller is responsible for these tasks, then they are indeed a primary actor in the banking process.

The concept of a bank robber in design hinges on creativity and scope, often seeming like an extension of a customer's use case However, the suggestion to "Steal the ATM!" introduces the potential for a movement detector, prompting a reevaluation of the robber's role This could lead to a scenario where the robber has a defined use case, albeit one that ultimately fails, or it may simply add more extension conditions to the existing customer use case.

The answers depend on which containing system you choose (see Figure B.1).

The ATM Not an actor for our purposes It is a now a component of the SuD.

The customer Still a primary actor and stakeholder.

The ATM card Not an actor, for the same reasons as in Exercise 4.2 (with the same disclaimers).

In the context of banking, if you selected "Bank with people" as the system, it represents your System under Discussion (SuD) Conversely, if you opted for the "Electronic Banking Network," it may serve as an actor, contingent on your ability to justify the services provided by the Electronic Banking System.

The front panel Not an actor for our purposes It is a component.

The role of the bank owner varies based on the chosen system and established service goals They may serve as a component within the bank, lacking primary significance, or emerge as a key player in the bank's operations, though they are likely not a central figure in the Electronic Banking System.

The serviceman A primary actor if a hired outside serviceman, a component if an employee of the bank and you chose the Bank as the SuD.

The printer Not an actor for our purposes It is a component.

The main bank computer system It is now a component of the containing system (either of them).

The bank teller Either a component (of the Bank) or possibly a primary actor of the Electronic Banking System.

The bank robber Same as for Exercise 4.2

U Summary (white): Take Someone out for Dinner, (this is a somewhat con- trived answer in the case of the ATM).

U Summary (white): Use the ATM,

U User goal (blue): Get Money from the ATM,

U Subfunction (black): Find the Enter Button,

The easiest way to ﬁnd the minimal guarantee is to ask, “What would make a stakeholder unhappy?” The stakeholders are the customers, the bank, and the banking oversight agency.

Customers will become dissatisfied if they do not receive their cash, especially if they are charged for transactions without receiving the expected amount They are particularly unhappy when debited more than the cash they actually receive Additionally, customers require a detailed log of all transactions to protect themselves against potential fraud.

The bank aims to prevent customers from withdrawing more cash than the amount debited, ensuring financial accuracy and security To safeguard against catastrophic failures, it requires a detailed transaction log that tracks the progress of each transaction, allowing for efficient error resolution Meanwhile, the oversight agency emphasizes compliance with established guidelines and prioritizes the production of comprehensive logs for all transactions to ensure accountability.

We ensure that the debited amount matches the dispensed amount, providing a minimal guarantee of transaction accuracy In the event of a catastrophic failure, a micro-log captures the transaction's processing status, and every transaction is meticulously logged for accountability.

The success of the transaction is ensured when the account is debited for the dispensed amount, not the requested amount—be mindful of any failure conditions The card is returned, the machine resets, and a transaction log is created.

Serviceman Put ATM in working order

Withdraw cash Deposit money Transfer money Check balance

SummaryUser goalUser goalUser goalUser goal

2 ATM reads the bank ID and account number.

3 ATM asks customer whether to proceed in Spanish or English.

5 ATM asks for PIN number and to press Enter.

6 Customer enters PIN number, presses Enter.

7 ATM presents list of activities for the Customer to perform.

9 ATM asks customer to say how much to withdraw, in multiples of $5, and to press Enter.

10 Customer enters an amount, a multiple of $5, presses Enter.

11 ATM notiﬁes main banking system of customer account, amount being withdrawn.

12 Main banking system accepts the withdrawal, tells ATM new balance.

14 ATM asks whether customer would like a receipt.

16 ATM issues receipt showing new balance.

Here is the streamlined version of Fast Cash, showing the actors’ intents.

2 ATM reads the bank ID and account number from the card, validates them with the main computer.

3 Customer enters PIN ATM validates PIN.

4 Customer selects FASTCASH and withdrawal amount, a multiple of $5.

5 ATM notiﬁes main banking system of customer account, amount being withdrawn, and receives acknowledgement plus the new balance.

6 ATM delivers the cash, card, and a receipt showing the new balance.

The sample features three types of errors, with the primary issue being that the use case does not pertain to logging in, despite what the name and description suggest.

The order-processing system is designed to streamline user interactions, focusing on a high-level summary use case Initially, the first six steps involve the login process, which should be categorized separately as they pertain to a different objective Notably, users frequently log into the system but rarely log out, indicating a need for improved session management.

To enhance clarity for users reviewing the use case, avoid using programmer constructs like "Exit loop," "end if," and "end loop," as they can be confusing Additionally, excessive "if" statements can clutter the writing It is essential to focus on clearly describing the user interface design and streamline the content for better understanding.

Some educators suggest using the phrases "The use case starts when " and "The use case ends when " as stylistic conventions, but these are merely decorative and often unnecessary Typically, individuals intuitively understand that a use case begins with the first step and concludes when the writing is complete.

In UML, the phrase "User then Use Place Order" highlights the includes relationship, emphasizing how the "use" signifies a connection between user actions and the subsequent order placement process.

I believe that using cluttered language hinders clarity in writing; therefore, I prefer to say "User places the order." It’s essential to adhere to the conventions established by your project team when referencing other use cases.

In conclusion, we identify two distinct use cases: the kite use case, which utilizes the Order Processing System, and the subfunction, Log In The Log In function can be inferred independently, while links to additional use cases are emphasized for clarity.

Use Case 38 Use the Order Processing System

2 System presents the available functions User selects and does one of:

3 This repeats until the user selects to exit.

4 System logs user out when user selects to exit.

Here is a sampling of failure conditions Typically, my classes produce a list twice this long Notice that all conditions are detectable and must be handled How did you do?

Card reader broken or card scratched.

Card for an ineligible bank.

Customer does not enter PIN in time.

Host computer is down, or network is down.

Customer does not enter amount in time.

Amount requested is too large.

Network or host goes down during transaction.

Receipt paper runs out or jams.

Customer does not take the money from the dispenser.

Use Case 39 Buy Stocks Over the Web

Minimal Guarantees: Sufﬁcient log information exists that PAF can detect that something went wrong and can ask the user to provide the details.

Success Guarantees: Remote web site has acknowledged the purchase; PAF logs and the user’s portfolio are updated.

1 User selects to buy stocks over the web.

2 PAF gets name of web site to use (E*Trade, Schwab, etc.)

4 User browses and buys stock from the web site.

5 PAF intercepts responses from the web site and updates the user’s portfolio.

2a User wants a web site PAF does not support:

2a1 System gets new suggestion from user, with option to cancel use case.

3a Web failure of any sort during setup:

3a1 System reports failure to user with advice; backs up to previous step.

3a2 User either backs out of this use case or tries again.

4a Computer crashes or is switched off during purchase transaction:

4a1 (what do we do here?)

4b Web site does not acknowledge purchase, but puts it on delay:

4b1 PAF logs the delay; sets a timer to ask the user about the outcome.

5a Web site does not return the needed information from the purchase:

5a1 PAF logs the lack of information, has the user update questioned purchase.

5b Disk crash or disk full during portfolio update operation:

5b1 On restart, PAF detects the log inconsistency and asks the user to update questioned purchase.

Use Case 40 Perform Clean Spark Plugs Service

Precondition: Car taken to garage, engine runs.

Minimal Guarantee: Customer notiﬁed of larger problem; car not ﬁxed.

Success Guarantee: Engine runs smoothly.

1 Open hood and cover fender with protective materials.

3 Wipe grease off spark plugs.

5 Test and verify plugs work.

7 Connect ignition wires to appropriate plugs.

8 Test and verify that engine runs smoothly.

10 Remove protective materials from fenders; clean any grease from car.

4a Plug is cracked or worn out: Replace it with a new plug.

8a Engine still does not run smoothly:

8a2 Notify customer of larger problem with car (UC 41).

ACTOR Something with behavior (able to execute an if statement) It might be a mechanical system, computer system, person, organization, or some combination of these.

An external actor is an actor outside the system under discussion

A stakeholder is an external entity with a vested interest that must be safeguarded by the system, necessitating specific actions to address their concerns Various use cases can involve distinct stakeholders, each with unique interests that the system must consider.

A primary actor is a key stakeholder who seeks to achieve a specific goal through the system While they usually initiate the interaction, it can also be started by an intermediary or triggered automatically by an event.

A supporting or secondary actor is a system against which the SuD has a goal.

An offstage, or tertiary, actor is a stakeholder who is not the primary actor

An internal actor is either the system under discussion (SuD), a subsystem of the SuD, or an active component of the SuD.

INTERACTION A message, a sequence of interactions, or a set of interaction sequences.

SCENARIO A scenario is a sequence of actions and interactions that occurs under certain conditions, expressed without ifs or branching.

A concrete scenario involves detailing all specific elements, including the names of actors and the values at play This approach is akin to narrating a story in the past tense, encompassing every relevant detail for clarity and engagement.

A usage narrative, often referred to simply as a narrative, presents a specific scenario that highlights the motivations and intentions of different actors involved This tool serves as an effective warm-up exercise for both reading and writing use cases, helping to clarify the context and purpose of the interactions within a system.

In requirements writing, general scenarios utilize placeholder terms such as "customer" and "address" to represent actors and data values These placeholders help differentiate abstract scenarios from specific, concrete examples when necessary.

A path through a use case and a course of a use case are synonyms for general scenario.

The primary success scenario encompasses a comprehensive narrative from initiation to completion, detailing the achievement of goals and any subsequent bookkeeping activities While it serves as a typical and illustrative example of a successful path, it is important to note that it is not the sole route to success.

An alternate course is any other scenario or scenario fragment written as an extension to the main success scenario.

An action step is the unit of writing in a scenario Typically one sentence, it usually describes the behavior of only one actor.

SCENARIO EXTENSION A scenario fragment that starts upon a particular condition in another scenario

The extension condition names the circumstances under which the different behavior occurs

An extension use case is a use case that interrupts another use case, starting upon a particular condition The use case that is interrupted is called the base use case

An extension point serves as a designated tag within a base use case, indicating where an extension use case can intervene It can identify multiple locations within the base use case, allowing the extension use case to aggregate all related behaviors that interrupt the base use case under specific conditions.

A sub use case is a use case called out in a step of a scenario In UML, the calling use case is said to include the behavior of the sub use case.

A use case outlines the behavioral aspects of a contract among system stakeholders, detailing how the system interacts and responds to requests from the primary actor It illustrates the system's behavior under different conditions, highlighting the achievement or failure of the primary actor's goals Additionally, the use case compiles various scenarios related to the primary actor's objectives.

FOCUS Whether the focus is on the business or the new system:

A business use case focuses on the operational aspects of a business rather than the technical functions of a computer system It can be developed for various goal levels but is specifically applicable at the enterprise or organizational scope.

A system use case focuses on the operations of a computer or mechanical system rather than business processes It can be developed at various goal levels and scopes, including at the enterprise level When written from an enterprise perspective, a system use case highlights how the system under development (SuD) influences the overall behavior of the organization.

FORMALITY How much energy, rigor, and formality are used:

A use case brief is a one-paragraph synopsis of the use case.

A casual use case is typically presented in a straightforward prose format, often lacking detailed project information and a comprehensive description, which are essential components of a fully dressed use case.

A comprehensive use case is developed using a complete template that outlines key elements such as actors, scope, level, trigger conditions, preconditions, and additional header information, along with relevant project annotations.

LEVEL How high or low the goal is:

A summary-level use case requires multiple user-goal sessions to complete, potentially spanning weeks, months, or even years Its sub use cases can vary in complexity and are visually represented by a cloud ( ) or a kite ( ) The cloud symbolizes use cases that include steps at the cloud or kite level, while the kite indicates use cases that consist of user-goal steps.

A user-goal use case addresses a specific and immediate objective valuable to the primary actor, typically completed by one individual within a timeframe of 2 to 20 minutes, or even less if executed by a computer This allows the primary actor to move on to other tasks afterward The steps involved are categorized at the user-goal level or lower, and visually, a user-goal use case is represented with wave symbols.

A subfunction use case addresses a specific aspect of a user-goal use case or another subfunction, consisting of detailed steps that represent lower-level subfunctions It is visually represented by a fish symbol ( ) or a clam symbol ( ) The clam symbol indicates that the use case is too detailed and should not be documented.

SCOPING How large or small the SuD is:

Tiêu đề	Writing Effective Use Cases
Tác giả	Alistair Cockburn
Chuyên ngành	Software Engineering
Thể loại	Book

Định dạng
Số trang	301
Dung lượng	5,48 MB