5.2 Steps

To create the Filled iteration artifacts, follow these steps:

1. Break out detailed use cases.

2. Create Filled use cases.

3. Add business rules.

4. Test the Filled use cases.

5. Put some things off.

5.2.1 Break Out Detailed Use Cases

During the Facade iteration, you created use cases for each major interaction. As you delve into more detail during the Filled iteration, you will find that some of these Facade use cases are too general and need to be broken down into several Filled use cases. This challenging task poses questions such as, What size should a use case be? Where is the natural breakdown between functionality?

Before we answer these questions, let's expand step 1, breaking out detailed use cases, into more detailed steps.

1. Add detail to the use case diagrams.

2. Review use case granularity.

5.2.1.1 Add Detail to the Use Case Diagrams

You created an initial set of use case diagrams for the Facade iteration. During the Filled iteration, you take the vaguely described Facade use cases and create Filled use cases, adding any other details that are uncovered as you get into greater detail in the text use cases. There is generally a one-to-one ratio of Facade use case to Filled use case, but not always. There are often new use cases uncovered once the details come up, resulting in Filled use cases that never existed in the Facade iteration. Also, some Facade use cases may break into two or more Filled use cases (see Section 5.2.1.2).

5.2.1.2 Review Use Case Granularity

Earlier we posed the question, What size should a use case be? "Size" does not refer to the amount of documentation that supports a use case, nor does it indicate how detailed a use case should be. Rather, it refers to how you define the boundaries between system functionality. Another way to look at the issue is to ask, How do we split system functionality into use cases? How many use cases should we employ to describe the system? These are questions of use case granularity .

DEFINITION:

Use case granularity is the relative scope of individual use cases compared to the application's scope.

You can describe a system in a few or a great many use cases. The fewer the use cases, the coarser the granularity of each use case.

Granularity is a relative measure, and there are no metrics established to determine correct granularity for all projects. Instead, you choose granularity that is appropriate for a specific development effort. Your goal in gathering requirements is to understand and communicate scope, complexity, and detail. The granularity you choose for documenting requirements must facilitate division of work among analysts and must allow ease of change. In addition, the granularity must be acceptable to your stakeholders.

The best way to finalize the granularity decision is to provide the team with guidelines and discuss the factors that guided the choices. Consistency and consensus are important criteria for successful granularity across use cases. One guideline that we've used successfully is to think of the iterations of design and development. Iterations are often set as one to three weeks. Making this assumption, think about what can be accomplished in one week (or two or three). Choose a single example of functionality and revalidate the requirements, doing analysis, design, construction, testing, and deployment. Given one of the paths (scenarios) of the use cases you've created, could your team implement it in a week? Two? Three? The answer to that question becomes a good acid test for use case granularity.

What differences will granularity make to the use cases? A too-fine granularity may not be able to provide true business value in a single use case, and that may make it difficult to grasp a business concept. A too-coarse granularity increases complexity and decreases readability.

After you have completed the initial identification of the detailed use cases, it is time to review their granularity and change it if necessary. Ask the following questions of the detailed use cases:

• Does each use case provide a sufficient "big picture" view of its functionality?

• If you broke down the use cases, would they be easier to understand?

• Can you make them easier to work on?

• If you needed to change some details in a use case, would it be difficult?

• Can one analyst work on one use case, or is it so big that two or more analysts would have to work on it?

• Could a reasonably sized team take one path (scenario) from the use case from requirements to deployment in one, two, or three weeks?

When you have found a granularity that works well, apply it also to the use case diagram. Group related use cases into packages, and draw a use case diagram for each package. The system context use case diagram shows the big picture, and each package's diagram will contain the detail for each set of use cases.

After you implement any changes due to granularity, review the use cases and their summaries to ensure that you have not omitted considerations of scope. Name and summarize any additional use cases, and then update the use case diagram. You will complete these use cases, so it is important to identify all the necessary use cases as placeholders at this time.

5.2.2 Create Filled Use Cases

Now that you have summarized all the use cases in the application (we hope!), you are ready to build each one. Because you have chosen an appropriate granularity, you can safely take the time to build the detailed use cases.

Stakeholder meetings have formed the input into most of these steps. If more information is needed, head back to the stakeholders to confirm, probe, and query.

The following sections show the steps for completing the Filled use cases.

5.2.2.1 Identify Triggers

A use case trigger is the impulse or event that initiates the use case.

Triggers answer the questions, When does this use case start? What impulse or event signaled the start of this use case? A use case may have more than one trigger. To help discover all the triggers, ask the stakeholder to describe the process flow.

Describe the trigger in the active voice ("The build manager asks the developer to build a product release") rather than the passive voice ("The developer is asked to build a product release"), and state the condition simply. Do not describe the trigger in terms of the software system; instead, relate it to the business being modeled . For example, a use case should not start when a user opens a window; instead, it should start when a sales agent receives a telephone order.

Clarify whether a trigger is also an automation requirement. For example, suppose that a trigger for a use case that captures a telephone purchase order is "Sales agent receives a telephone call." The problem with this description is that it does not specify whether the telephone or the sales agent triggered the use case. Talk to the stakeholders about the level of automation they require, and document it clearly to avoid this kind of ambiguous requirement. In such a discussion, it is useful to distinguish between "possible but expensive" versus "realistic" requirements.

Here are examples of triggers:

• The build manager asks the developer to build a product release.

• The system detects a work file in the inbound processing queue.

5.2.2.2 Identify Preconditions

Preconditions describe a mandatory state of the system at the inception of the use case.

A precondition is anything that the use case assumes has occurred before its starting point that is relevant to the use case. Describe the business conditions that must precede use case initiation. Ask the stakeholder questions such as, What must happen before we can do this? What do you need to have before you can perform this functionality?

Examine the inputs to the use casewhether the input is a piece of information (such as a form) or an event (such as someone retiring )and ask how this use case will be aware of it. For example, suppose that in your use case, the actor keys data. Ask where the data came from. If it is mailed and if this is the first time the system comes into contact with it, then a precondition is that the data entry sheets are available. A related trigger could be that at least ten data entry forms have accumulated .

Preconditions and use case triggers are related. Together, they describe the state of the system when the use case starts. The difference between a precondition and a trigger is that satisfying the preconditions is not, by itself, a sufficient condition to initiate the use case, the trigger will provide the impetus to start the use case, and that initialization will be successful only if the preconditions have also been satisfied. All preconditions must be satisfied for the trigger to be able to initiate the use case.

Also note that a condition should not be included in both the precondition and the exception area of a use case. If the condition is included in both, you have introduced redundancy. The exception cannot occur because the use case would not begin until the condition was satisfied.

Another use case, an actor, or a system actor must be capable of satisfying all preconditions of any use case.

5.2.2.3 Refine the Use Case Name

The name of a use case describes the primary actor's objective. This is a noun-verb combination.

Ask the stakeholder to define the most important objective of the use case. Answering this question is difficult, so encourage the user to explore the possibilities and to examine the use case's completion criteria. One area that confuses users when discussing objectives is this: From whose perspective should the objective be considered ?

For example, in a book-ordering system, the customer's criterion for use case completion is that she receive the book that she ordered. From the perspective of the sales clerk, the objective is to collect the order, address, and payment information and to send the order to the dispatching warehouse.

The use case name should reflect the objective of the primary actor. In our example, the sales clerk is the primary actor, and the customer is a secondary actor, so the use case name should be Create Sales Order . To avoid confusion when you name use cases, discuss with the stakeholder which of the actors is the primary one. In addition to helping you identify a good use case name, gaining a clear understanding of the objectives will improve all areas of the use case.

Section 4.3 describes several tools that help in this process, including a use case name filter that helps you avoid using weak use case names .

5.2.2.4 Refine the Actors

The use case actor is an abstraction of any role that interacts with the use case.

The use case diagram indicates the roles that interact with a use case as actors. These are the stick-figure people attached to the use cases. Each actor is a role and can represent a person or a system.

It is important that you understand "who does what" in each use case. Ask the stakeholder questions such as What roles are involved in this task? How do they interact? To prevent confusion regarding similar roles, collect any relevant information about each actor in an actor profile. For example, if an actor is someone who sometimes works remotely, record this in the profile.

5.2.2.5 Specify the Basic Course of Events

The Basic Course of Events section of a use case specifies the actor's interactions with the system and with other actors to achieve the actor's goals. The events tell a story that describes how a triggered use case progresses toward its objective and the steps in between.

Write the basic course of events as numbered instructions that tell the actor what to do and that show how the system responds.

For example, let's say that during the Facade iteration, a use case called Enter Tenant Details (see Appendix A) has the following summary and little other information:

The system stores a set of details about each tenant (lease holder).

In Use Case 5.1, we add the Basic Course of Events. Each statement in the Basic Course of Events section is part of the dialog between the actor and the system. This section describes the straight line through the process; variations and exceptions have their own section. The information in the basic course of events comes from your interview with the stakeholders. Have the stakeholders describe how they envision the actor achieving the objectives of the use case. Ask them to list all the steps that they can think of. This information will give you the first cut at the course of events. Go into detail for these steps. If they say, "We enter the customer's demographics ," ask them to elaborate on these details. Ask, What happens if . . . ? If there are multiple actors in a use case, ask, Who does what? Don't be afraid to ask persistent questions. Repeat the interviews to clarify any details that remain obscure.

Use Case 5.1 Enter Tenant Details

Use Case:	Enter Tenant Details
Description:	The real estate system tracks who is leasing a property; the system stores a set of details of each tenant (lease holder) for billing, tracking, and exposure reasons.
Triggers:	A new tenant or potential tenant has been found for a property leasethis could be initiated from the lease property use case. Additional or changed information has been found for an existing tenant.
Basic Course of Events:	The actor navigates to the tenant area. The actor enters the identification information for a tenant. First name, last name, and SSN are entered for an individual; or Company name and federal tax ID for an institution or organization. The system checks for existing matching entries. The system displays a data entry template that is populated with any existing information. The template differs for individuals and organizations. <list of data items>. The actor enters each data item. The system validates data according to the data entry rules (dates, etc.). When satisfied with the data entry the actor commits the changes. The system validates that the data set is complete. The system stores the changes, and if validation passed the tenant is marked as validated .

If there is an existing system or manual process, it makes it easier for the stakeholders to give you the detail needed for these steps. If there is no existing system, encourage them to imagine it and to think of all the detail they need for the process. Walk the stakeholders through the steps to encourage them to remember additional details.

The Basic Course of Events section must expose complex processes and reveal simple, easily read steps. To " open the black box" and make the process clear is your goal for writing this section. Aim to elaborate a process sufficiently to reveal all its intricacies.

Avoid naming user interface controls in the steps. Always translate the requirement into a format that excludes GUI specifics, and ask the stakeholder for the underlying requirement. For example, don't write, "Click the OK button." Instead, write, "Save the demographic details."

TIP:

Maintain a glossary of all the business terms included in the use cases. The glossary should explain the terms used and has the dual function of clarifying and confirming your use of the specific terms. This action reduces jargon confusion between stakeholders and analysts during the requirements-gathering activity, and it clarifies your use cases to the designers.

5.2.2.6 Indicate Repetition

Repetition is the reiteration of a process by an actor until a condition changes.

The basic course of events must often show repeating steps as well as alternative paths and exception paths. Use a tiered numbering scheme to indicate repetition. For example:

1. Indicate customer's color choice from the set displayed.

2. (Optional) Indicate as many as five alternative choices.

3. Go on to the next step.

Ask, What is the condition for ending the repetition? Will there be the same number of repetitions each time? Then translate the answers into the requirements that the user interface designers and data designers must know. Additionally, this information is valuable for defining scope.

5.2.2.7 Document Exceptions

Exceptions specify the actor's interactions with the system, and with other actors, when the basic course of events is not followed.

The exceptions and alternatives listed in Use Case 5.2 apply to the Basic Course of Events section of Use Case 5.1.

Use Case 5.2 Exceptions and Alternatives Sections of Use Case 5.1

Exceptions:

3. If the system finds a duplicate, alter the actor and display the existing tenant record.

8. If mandatory data is missing, the system alerts the actor and explains the omission. If the tenant refers to a current lessee (that is, a tenant with an active lease), and the system will not accept changes, that will cause the tenant to lose validation status.

7. If the actor is not satisfied with the changes, the actor optionally may abandon the changes. The system reverts to the previously stored record if one existed.

The exceptions have their own section in the use case template, immediately below the Basic Course of Events section. If there is ambiguity regarding which step the exception relates to, clarify by referring to the step's number. If the description of the exception requires multiple statements, use tiered numbering like that used in the Basic Course of Events section. The default is to return to the next event statement; if that is not the default, show the event number to return to. If an exception ends a use case, state it.

Write your use cases so that all levels of users are comfortable reading them. When you are writing exceptions, avoid the use of IF-THEN-ELSE construction. Such pseudocode breaks the flow of the use case story, and executive-level users may not be comfortable with it. Write exceptions so that they can be read naturally, and do not capitalize words such as otherwise .

The Basic Course of Events section specifies the straight line through from trigger to use case completion. This is the basic process. Most use cases have exceptions in response to specific circumstances. We document these because the system must be able to handle them. Exceptions document the answers to the range of questions that begin with, What will the actor do if . . . ?

Identify the business process exceptions to respond to real-world inputs; do not document possible software exceptions. To identify the relevant exception, discover how the actor should interact with the system when the process deviates from typical processing. In this way, the use case can describe the interaction between actors and the system that accomplishes real business. Ask the stakeholder what-happens-if questions to discover the exceptions. But be sure to distinguish between exceptions and improbable occurrences. The focus of most business development is to create a system that functions correctly for the majority of the business cases that it handles. Typically, the system designers decide not to explicitly handle every possible business exception. Embedded systems and mission-critical systems may need to handle a larger set of improbable conditions. As with the majority of the rules surrounding use cases, you are free to make and break them as you choose.

When Should You Make an Exception into a New Use Case?

While writing use cases, guard against creating a use case that is too large to be managed. When the size of an exception is comparable to that of the use case, it can be a warning signal that the exception, even if it appears to be related to the use case, should be a separate use case.

If your exception is too large or if it has exceptions of its own, create a separate use case for it. At this point do not relate it to other use cases with include and extend relationships. Do this in the next iteration.

5.2.2.8 Refine the Use of Language

It sounds basic, but grammar and spelling in your use cases are important. Use cases are written in natural language, so the only syntax that guides you when writing them is the use of language. You can be sure that your work will be judged on the quality of the writing in the use cases as much as anything else.

In general, use the active voice ("The actor did it") rather than the passive voice ("It was done by the actor"). Writing in the passive voice may be a clue that information is missing. If you're saying, "It was done," without specifying who did it, perhaps it is time to find out who did it.

Also, try to keep technical jargon out of your use cases.

5.2.3 Add Business Rules

Collect the business rules in parallel with developing the use cases and identifying the nonfunctional requirements. During the Filled iteration, you are simply adding business rules as they appear during use case creation. At this point there is no need to comply with strict formats or categorizations for business rules. You can apply these in later iterations.

5.2.4 Test the Filled Use Cases

After you have built the use cases, check their completeness and quality. Because the use cases are not ready to be examined by the stakeholders, this should be an internal review. It is for your benefit only. It allows you to identify vague points in your use cases and to return to the stakeholders for clarification .

Employ scenarios for testing use cases. Chapter 2 defines a scenario as a possible path through a use case. Create a scenario by choosing data that will drive a use case through a specific set of main flow and exception statements.

Apply a scenario by reading each step, supplying data to it, and obeying the use case's rules. Applying a scenario allows you to walk through a use case by following the flow and exceptions dictated by the data. This process helps you identify missing steps and discover additional exceptions, and that makes it a useful tool for quality-checking your work.

Each use case may have many possible scenarios. You may want to create scenario data for the normal processing scenario and for the more important exceptions. Scenarios do not have to be formalized or recorded to be an effective testing tool.

While you walk through a scenario, ask whether the use case documents the modeled system sufficiently. Test a use case comprehensively by executing a scenario for each path in the use case. Check that the exceptions are called and that the use case handles each exception.

Scenarios can be used to test both system requirements and the finished product. If you do formalize a scenario, it will be useful to the testing team. See Appendix A for additional detail on how to leverage your use case efforts throughout the software development lifecycle.

Helping Users Help You Test a Use Case

How do you guide users through testing a use case, given the differences between use cases and scenarios?

When a user is explaining to you the rules from which a business process executes, both of you can experience a great deal of ambiguity because of the differences in how each of you views the events. The interviewer tends to ask the questions in use case language, and the interviewee tends to provide answers in "scenario land." Business users typically describe the set of circumstances in which they find themselves . If they have a specialty within the business process being described, their descriptions of the straight line path and the exceptions will reflect it. Under these circumstances, the dialog is likely to be misleading.

Be especially aware of the potential for this problem when the user is describing scenarios without first describing the main path and listing the exceptions. For example, if the business user says, "The customer calls to verify the order that was received via the Web," this is a danger sign. It is possible that the conditions described actually reflect an exception and not the main flow. Ask questions to determine whether this is so and to determine the additional paths that the business process could follow.

5.2.5 Put Some Things Off

Certain tasks should be put off until later iterations. The Filled iteration is the time to expand the detail of the documented requirements but not to increase or decrease the scope dramatically. It is good to wait on the following tasks :

• Identifying common behavior and merging use cases

• Handling software exceptions

Above all, keep working on gathering what and not how . Keeping this focus can be difficult because describing the how alleviates people's fear that they are being misunderstood or the fear that the system will not match their expectations. When you are given a description that includes a how component, look for the reason it was expressed during requirements gathering. Perhaps an additional nonfunctional requirement lurks behind the veil of design assumptions. For example, suppose that a requirement is expressed as follows :

When the user has entered the salary, interest rate, and credit rating, the system stores the profile and calculates a band of possible loan amounts. The calculation must be performed on the server and never on the client.

Note that the last line of this requirement contains how information. A design decision has been expressed. If you inquire further into this statement, you may discover that the user community is worried that the calculation will not be made quickly because a previous legacy system performed the calculation on a client machine, which took several minutes. The unstated nonfunctional requirement is actually that the calculation result be returned to the user within, say, three seconds.

Here's another example:

The data system passes the Social Security number to the imaging system via API calls that will bring up the folder of personal information about the account holder through which the user can browse.

The specific how elements in this requirement are the mention of API calls and the use of Social Security numbers as a unique identity in an imaging system. Further conversation with this user may indicate that he wants it documented that the imaging system is integrated with his business system and that he will not have to invoke the imaging system manually to search for an account. It is a simple step to remove the unique key and API references from this requirement and still describe the interaction successfully.

Also, do not worry about the user interface requirements at this point. The way the application presents or accepts information to and from the users (the how ) is a detail that should wait until a later iteration.