Guideline: Detail Use Cases and Scenarios
This guideline provides help on detailing use cases and scenarios.
Main Description

Most efficient way to write use cases

Because use cases model requirements, they are highly dynamic by nature. The more we examine a scenario, the more we learn and the more things change. To further complicate the issue, changes to one use case can lead to changes in others. Therefore, we want a flexible, highly efficient method for writing use cases that maximizes stakeholder value and minimizes risk early in the project and minimizes costly rework later.

An iterative, breadth-before-depth approach is best. This breadth-first approach involves two aspects: finding and outlining use cases and detailing individual use cases.

Finding and outlining use cases

Use cases exist in sets, and the relationships between the various use cases and Actors are important. As you learn more about the Actors, you also learn more about the system's boundaries and transactions. Likewise, as you learn more about the system's transactions, you learn more about its Actors. Therefore, it is more efficient to capture and outline the primary use cases before detailing individual use cases. This way, you can identify and understand the importance and risk associated with each use case before committing time to detailing them.  This aspect of the breadth-before-depth approach is embodied in the process by the explicit separation of two tasks Find and Outline Requirements and Detail Requirements

Detailing individual use cases

Similarly, it makes sense to write each individual use case iteratively. Start by detailing the main scenario.  As you do this, you can identify various alternative and error flows that the use case might follow, and then evaluate, rearrange, or eliminate them and prioritize them before detailing the surviving scenarios, so you can focus your effort in the right place.

The level of detail that you capture depends on several factors. See Guideline: Use Case Formats for guidance on selecting the correct format for your use cases.

Detail the basic flow of events (main scenario)

As a starting point, use the step-by-step description of the main scenario that you created during Task: Find and Outline Requirements. Then, gradually add details to this scenario, describing what the use case does, not how to solve problems internal to the system.

A flow of events description covers:

  • How and when the use case starts
  • When the use case interacts with the Actors and what data they exchange
  • When the use case uses data stored in the system or stores data in the system
  • How and when the use case ends

It does not describe:

  • The GUI
  • Technical details of hardware or software
  • Design issues

Describe the flow of events for the main scenario in the form:

  1. The use case starts when <Actor name> <does something>.
  2. The system <does something in response>.
  3. The <Actor name> does something else.

See Section 4 of Example: Use-Case Specification for a sample completed basic flow.

Detail alternate flows

A use case consists of a number of scenarios, each representing specific instances of the use case that correspond to specific inputs from the Actor or to specific conditions in the environment. Each scenario describes alternate ways that the system behaves, or it may describe failure or exception cases.

Review the list of alternative flows that you captured during Task: Find and Outline Requirements. As you detail the main scenario, you may identify additional alternate flows by asking these questions:

  • Are there different options available, depending on input from the Actor? (Example: If the Actor enters an invalid PIN number while accessing an ATM.)
  • What business rules may come into play? (Example: The Actor requests more money from the ATM than is available in her account.)
  • What could go wrong? (Example: No network connection available when required to perform a transaction.)

It is best to develop these scenarios iteratively, as well.

  1. Begin by identifying them.
  2. Examine each possible scenario to determine whether it is relevant, that it can actually happen, and that it is distinct from other scenarios.
  3. Eliminate redundant or unnecessary scenarios.
  4. Prioritize the remaining scenarios and start detailing the more important ones.

In addition to the detailing the flow of events of each alternative flow in the form described above, each alternative flow should describe:

  • Where the alternative flow can be inserted in the basic flow of events
  • The condition that needs to be fulfilled for the alternative behavior to start
  • How and where the basic flow of events is resumed, or how the use case ends

See Section 5 of Example: Use-Case Specification for examples of completed alternative flows.

Structure the use case

It is useful to structure the use case according to scenarios. This helps both to simplify communication and maintenance and to permit the use cases to be implemented iteratively. Name and describe each key scenario so that these may be prioritized, assigned to an iteration and an individual, and referenced from the Work Items List for implementation.

In addition to structuring the use cases according to scenarios, it is often useful to structure the scenarios themselves into subflows. This provides an additional level of granularity for planning work and tracking progress. Unless a subflow involves only a minor part of the complete flow of events (which can be described in the body of the text), describe each subflow in a separate section of the Flow of Events section. Subflows that should be in a separate section include these examples:

  • Subflows that occupy a large segment of a given flow of events.
  • Exceptional and alternative flows of events. This helps the use case's basic flow of events to stand out more clearly.
  • Any subflow that can be run at several intervals in the same flow of events.

If there are subflows identified that are common to multiple use cases, you can re-factor your use-case model to include these. See Concept: Use-Case Model for more information on the <<include>> dependency.

For more information on structuring the use case, see the "Flow of Events - Structure" section in Concept: Use Case.

The Template: Use-Case Specification provides a suggested structure for the use case specification. See Example: Evolution of the Use-Case Model and Example: Use-Case Specification for examples of structuring the use-case model and use case specifications, respectively.

Detail special requirements

Be sure to also capture any requirements that are related to the use case but are not taken into consideration in the flow of events of the use case. These requirements include business rules, design constraints, usability requirements, performance requirements, reliability requirements, supportability requirements, and interface requirements. These requirements all influence the implementation and associated cost as much as the flow of events. Therefore, they must be agreed upon and prioritized.

Typically, nonfunctional requirements that refer to a specific use case are captured in the Special Requirements section of the use case. For more information, see the "Special Requirements" section in Concept: Use Case.

If there are nonfunctional requirements that apply to more than one use case, capture these in the Artifact: Supporting Requirements Specification. For more information on supporting requirements, see Concept: Supporting Requirements.

For guidance in writing clear, concise, unambiguous special and supporting requirements, see guidelines Writing Good Requirements and Requirement Pitfalls.

See Section 8 of Example: Use-Case Specification for examples of special requirements.

Describe preconditions and post-conditions

A precondition of a use case explains the state that the system must be in for the use case to be able to start. Be careful in describing the system state. Avoid describing the detail of other, incidental activities that may already have taken place.

A post-condition of a use case lists possible states that the system can be in after the use case runs. The system must be in one of those states. A post-condition also states actions that the system performs at the end of the use case, regardless of what occurred in the use case. Post-conditions may be categorized as Minimal Guarantees or Success Guarantees:

  • Minimal Guarantees represent conditions that will be true when the use cases end, regardless of how they terminate.
  • Success Guarantees represent condition that will be true when the use cases end successfully, regardless of which paths they took.

Consider the following when specifying preconditions and post-condition:

  • The states described by pre- or post-conditions should be states that the user can observe. "The user has logged on to the system" or "The user has opened the document" are examples of observable states.
  • A precondition is a constraint on when a use case can start. It is not the event that starts the use case.
  • A precondition for a use case is not a precondition for only one subflow, although you can define preconditions and post-conditions at the subflow level.
  • A post-condition for a use case should be true regardless of which alternative flows were executed; it should not be true only for the main flow. If something could fail, you would cover that in the post-condition by saying "The action has completed," or if something failed, "The action was not performed," rather than just "The action is completed." 

For more information, see the "Preconditions Post-conditions" section in Concept: Use Case.

See Section 7 of Example: Use-Case Specification for example pre- and post-conditions.

More Information