A PM’s Guide to Use Cases Part 3: Use Case Narratives

Originally published in PM Times on December 8, 2015.

---

As promised, this is the fifth article in our modeling series and the third on use cases. We’ll start with a short summary of the main concepts covered previously.

SUMMARY OF PREVIOUS ARTICLES

Here are the highlights of the requirements modeling articles written to date:

• To get good requirements, we need to ask the right questions. We need to ask both high-level consultative questions to determine the true business need, as well as questions about the features, characteristics, and functionality needed to develop the end product (solution). Modeling helps uncover requirements related to these product features and functions. Asking questions enables us to model the requirements. Modeling requirements, in turn, uncovers gaps that lead to further questions and ultimately helps us deliver the product that our stakeholders want and expect. For more, view part 1 of the modeling series.
• A model is a representation of reality, like a model car, airplane prototype, or graphical design (e.g., a CAD drawing) of a house. As they relate to requirements, models usually consist of text, graphics representations, or both. For more, view part 1 of the modeling series.
• As PMs, we might not do business analysis work ourselves, but we need to ensure that work is done. So it’s important for us to be able to have enough understanding of these models to ask the right project questions of the resources who will be doing the elicitation and modeling. For more,
  view part 2 of the modeling series.
• There are different categories of requirements, including data and process. Use cases describe a third category—interaction. When we use any kind of user interface, such as a mobile phone app or enter any information into any screen or web page, we are interacting with the “system.” Use cases describe this interaction between us (actors) and the system. For more, view part 1 of the use case series.
• In other words, a use case describes the conversation back and forth between actors and a system. The system contains all the work we want to do on the project, and a use case diagram is useful in helping us determine this scope of work as it relates to the final product. Actors always interact directly with the system, but are always outside the system. They can initiate a use case, provide input to it, and/or receive outputs from it. Actors can be people, other systems, time triggers, or event triggers. For more, view part 1 of the use case series.
• Use cases help our projects in two very different ways. Use case diagrams are immeasurably helpful in understanding scope and the use case narrative is invaluable for getting the detail needed to build the product or service. Although used primarily in software development, use cases are also helpful when creating processes and developing equipment. They work wherever there is interaction between people and what those people need to do. For more, view part 1 of the use case series.
• Use case models contain the use case diagram that we described in the last article and a textual description of each use case shown on the diagram. We have described the diagram in great detail in the last two articles. Here, we will describe the purpose of the use case narrative, the five questions these narratives help answer, and how invaluable this information is to both the business stakeholders and development team.

USE CASE NARRATIVES

The use case diagram shows the use cases, which are the features contained in the system. Each use case is shown as an oval and named as a-process with a verb to describe the action, such as Request Item or Ship Item. Use case narratives describe the process steps inside each use case. The narratives are needed because while it is great to see the features at a glance, no one really understands what these process names mean until we describe the detailed steps. If we told a developer to build a feature and all we gave them was the name “Request Item,” they would have to ask tons of questions and/or make lots of assumptions about how people would interact with the system when they wanted to request items from a website. We have found that those developers who actually read them love these narratives because they save so much time.

Below is an example of a use case narrative that describes the process steps involved in reserving an item in inventory in an Order system. To create the narrative we include the following:

• A number and name that identify the use case. These are often assigned according to the organization’s standards, templates, and/or requirements processes.
• The pre-and post-conditions describe the scope of each use case. Since each use case begins and ends, we need to tell it where to begin and when to end.
• A matrix with what the actor does and how the system responds to each actor request.
• Primary, alternate, and exception flows, which we explain below.

Below is an example of a use case narrative. The numbers on the use case narrative correspond to five important questions that use case narratives answer and which are listed below the narrative example.

1. At what point is the use case ready to begin? That is, what has to occur before the use case process can begin? Our example is about what the system does to reserve an item in inventory after it has been requested by a customer. When does this use case begin? Is the customer already logged in? Can they reserve items without being identified as a customer? These are business rules that have to be answered by stakeholders. Is the system available? Which user interface (screen/web page) are they on? The use case pre-condition answers this important question and if it is not known when the developers start working on it, they will struggle and lose time arguing about it.
2. When is the use case complete?  In other words, when is done “done?” What do we mean by complete? That’s another tricky question to answer. The use case narrative answers this question in the post-condition(s). The post-condition(s) together with the pre-condition set the boundaries of the use case. Again using our example, is the use case done when the item is shipped to the customer? When the item information is sent to the warehouse for packing and shipping? We don’t know and we should not assume. If the use case is about reserving items in inventory, shipping the item to the customer is clearly out of scope for this use case, although in scope for a different use case, one relating to shipments.
3. What is the most common way of getting from the beginning of the use case to the end? That is, from the pre- to the post-condition. This is our primary path, sometimes known as the happy path. Let’s have a quick peek at the happy path. We always start with the actor action and always end with the system response, or how the system responds to the actor request. The system response lists all the process steps in response to an actor action until another actor, if any, triggers another response from the system. These steps continue until the post-condition is reached.
4. What other ways can we get from the beginning to the end? These are our alternate paths. We’ll reach our post-condition, but not in the most routine way. That is, we’ll take a different route. Sometimes we return to the main path, sometimes not. In the above example, we return to the primary path.
5. What might prevent us from reaching our post-conditions? These are our exceptions. Exceptions take us off the path entirely and terminate the use case.

To better explain this example, let’s use the example of getting home from work—in this case by car. Let’s say that our pre-condition is that we have left our office building. Our post-condition is that our car is parked in our garage at home. Our routine way to get home is to drive on the interstate. Some days, however, the traffic is so bad that we take side roads. We still get to our post-condition, just in a different way. This path, then, is the alternate path. However, let’s say that we try to start the car and the car won’t start and has to be towed some place for repairs. That is an exception that prevents us from reaching the post-condition.

TEST SCENARIOS, ACCEPTANCE CRITERIA, AND “GIVEN-WHEN-THEN”

The three narrative flows are similar to test case scenarios. One of the advantages of taking the time to create use case narratives is that test scenarios will be pretty much complete as well. In addition, the post-condition(s) will help us determine the acceptance criteria. Finally, many Agile projects use a “given-when-then” format to help with testing. The use case narratives provide this information. The “given” is the pre-condition(s), the “when” are the actor actions, and the “then” are system responses. Let’s refer to our use case narrative example.

Given that the system is available, the customer is logged on, and that the customer has navigated to the page to enter line items, when the customer enters the item number, then the system verifies the number with a digit check verification, and so forth.

SUMMARY

Use case narratives take time to create. However, it’s not creating the model that takes the most time. It’s the thought process about the interactions between actors and the system that take the most time. The time that it takes to think through these interaction steps is time that has to happen regardless of what format is used to document it. Use case narratives provide a structured way to get us through the thought process, helping us ask the necessary questions, and giving us complete interaction requirements, which are needed to build a solution that works for our stakeholders.