Documenting Use Cases

Use cases can be documented quite extensively. One can include activity diagrams to model primary and alternate scenarios of the use cases, and sequence diagrams to model interaction between various actors and the system. Although one could model sequence diagrams for use cases, in most cases you will find that the activity diagrams are sufficient for documenting the various use case scenarios. Again, you do not have to have an activity diagram for every use case; use it to explain complex scenarios.

The use case documentation should be augmented by text that explains the main flow of events (primary scenarios) and alternate flow of events (secondary scenarios). These flows of events are documented in the language of the problem domain. Recall that a use case describes a set of sequences, therefore other than the main flow we need alternate flows to document those sequences that support exceptional behavior resulting from changes in system state, application exceptions, or an actor exercising different options. Each sequence or scenario is an instance of the use case the same way an object is an instance of a class. The flow of events must state the event or action that starts a use case, and it must clearly state how the use case ends. It must also include interactions with actors; this could include actions taken by the actor for requesting a system service or actions taken by the system for requesting service from the actors. The steps in a scenario are expressed as request-response interactions; for example, an actor requests a service and the system responds with an action. Scenarios are always written from an actor's viewpoint. This flow of events could be numbered for improved readability and may also contain preconditions and postconditions. We will see numbered flows of events, preconditions, and postconditions in Chapter 2, dealing with information architecture, where we will further elaborate a limited number of use cases using wire frames.

Use case documentation must clearly explain the purpose of the system without being too specific or too brief to cover essential system behavior. Focus should be on being complete rather than detailed in requirements analysis. Use cases have this duality of capturing requirements and expressing these requirements as behavior from an actor's viewpoint. Tailor the documentation to your audience and ask yourself, "Will the documentation effectively communicate the purpose of the system to the stakeholders, QA engineers, web production engineers, designers, and developers?" It may also help to engage a technical writer for documenting use cases. In this chapter, we are going to focus on a higher level of abstraction and then elaborate the use cases in Chapter 2.

Documenting Scenarios with Activity Diagrams

Activity diagrams model the dynamic aspects of a system. During use casing, an activity diagram helps a modeler to comprehensively depict a use case's dynamic behavior and its interaction with actors. Other than clearly articulating the flow of events for the stakeholders and developers, the knowledge derived from creating activity diagrams can be applied for adjusting the architecture such that conceptually and semantically related use cases with high degrees of cohesion are allocated in the same package. The cohesion between use cases is represented using the include or extend relationships, as explained in the next section, "Factoring Common Behavior and Variant Behavior." Should a readjustment in architecture lead to a use case being reallocated to another package, then any previously existing "include" relationships will become a "dependency" relationship.

Although the interaction diagram focuses on objects passing messages to each other, the activity diagrams focus on messages passed between objects. The messages make up the activity state in an activity diagram. The level of abstraction for depicting states in an activity diagram depends on whether you are using an activity state or an action state. An activity state is non-atomic and can be further decomposed in more activity states and/or action states. An action state represents an executable atomic computation that cannot be decomposed any further. A transition from a source state to target state is triggered by the completion of all activities in the source state.

Tip

In an activity diagram, the transitions leaving a decision node (diamond-shaped node) can be labeled with guard conditions. These guard conditions represent if-else scenarios. Also, you can label a transition as an event.

Factoring Common Behavior and Variant Behavior

Use the "include" relationship to factor common behavior in use cases. Factoring common behavior into separate use cases makes the system modular and promotes reuse. Later, in section "Manage Donor and Donations" (Figure 1-5), you will observe that the Register Donor process always includes Manage Donor Preferences; this is because donor preferences are always set the first time the registration process is instantiated. Also, Checkout includes Update Donation History because a successful checkout results in the creation of transaction history.

Figure 1-5: Use case diagram—Manage Donor and Donations

The include relationship is used when a use case is always going to be included in another use case. Its execution is not conditional. For conditional includes, use the extend relationship. The extend relationship differs from the include relationship in that the use case in an extend relationship conditionally injects itself into a base use case, at predetermined extension points. Factoring variants helps isolate exceptional behavior into separate use cases thereby simplifying the base use case.

An include relationship is represented by a directed link from the including use case to the included use case; an extend relationship is represented by a directed link from the extending use case to the use case that it extends. In the use case model, the include and extend relationships are rendered as stereotypes. In the flow of events, use the notation "include" (included use case) to include the behavior of another use case, as shown in the Checkout and Register Donor use cases in the package Manage Donor and Donations. Both include and extend must instantiate within the system boundary of its base use case; in other words, include or extend relationships cannot span between use case diagrams.

Creating a Use Case Summary

Consider a use case summary as an initial milestone in the requirements analysis effort. A use case summary is critical for several reasons:

• For quickly and accurately identifying the behavior of the system to stakeholders

• For requesting appropriate project funding and staff for subsequent phases of the project

• For project managers to prepare project plans

• For communicating requirements to the next phase of the project

• For fast ramp-up of individuals coming onboard the project team in the middle of the project

In this section, we will explain all the packages of the GreaterCause application, and their subordinate use cases and associated flow of events. Although explaining UML is beyond the scope of this book, wherever essential, we will explain how to appropriately use certain key notations accompanied with practical examples. The documentation style used in this book is suggestive and not prescriptive. You may have a variation of this based on your unique environment and team dynamics. For further information on applying use cases and associated techniques please refer to "Applying Use Cases" by Geri Schnieder et. al. [Use Cases], "Use Case Driven Modeling with UML" by Doug Rosenberg [Object Modeling], and "The Unified Modeling Language User Guide" by Grady Booch et. al. [UML].