UMLScenarios, Sequence Diagrams, and Narrative Text

The previous page in this series discussed the use case diagram and how it represents user populations and the tasks those users perform. The problem with modeling tasks in this way, at least if this is all you do, is that use case diagrams by themselves are just abstract ways of describing user tasks. Both HCI technique and object-technology practice suggest that describing concrete examples of how each task can be performed is the best way to verify that a task model accurately reflects what users do. At the same time these concrete examples flesh out the task model in a way that helps define both the procedures performed by the task and the user concepts manipulated by those procedural steps.

Narrative Scenarios

The first and easiest way to describe a concrete example of a task's performance is to describe it in a mini-story. We call this story, a Narrative Scenario. Here is an example of a narrative scenario for the Create Order task discussed on the last page:

1. The user starts the Create Order Task.
2. Create a new Order with a system assigned sequence number (order number).
3. Open the Order-Creation View using the new Order and display it to the user.
4. Enter an Item Number and Quantity.
5. Activate the Add command.
6. Inform the Create Order Task that the Add command has been activated.
7. Get Item Number and Quantity from the Order-Creation View and validate those values.
8. Create an Order Item using the Item Number and Quantity.
9. Add the newly created Order Item to the Order.
10. The user activates the Save command.
11. Inform the Create Order Task that the Save command has been activated.
12. The Create Order Task saves the Order.

Notice that everything flows from user actions and even when the system, through the Create Order Task, is driving the action, it is in direct response to what the user requested and the things being manipulated are described with user terms.

Once you have written the narrative text, identify all of the principal objects (Order, Order Item), object attributes (Item Number, Quantity), tasks (encapsulated behavior, in this case Create Order Task), actions (Add and Save), and chunks of user interface (Order-Creation View) by either underlining or printing in bold, as in the above narrative.

Even this simple example shows all of the parts of software specification. To start with, what does this user do? This is described at two levels, the larger user task (Create Order) and atomic actions (start the task, Add an item, enter values, and Save). We also see how the system responds. In this case, the creation of an Order Item, the validating of values, and saving the entire Order and Order Item structure. We also see what user concepts are employed: Order, Order Item, Item (implicitly), and Quantity. Finally, we also see what sort of presentation is needed. We have an object called Order-Creation View that must display Order Items and their Item Number and Quantity.

You've also probably seen the holes in this narrative. We should add something about identifying who the customer (buyer) is, getting or verifying their address, determining the method of payment and shipping, and so on. All of this content should appear in this single narrative though we may extend it by referencing other use cases (tasks) as in the following extended version of the first narrative:

1. The user starts the Create Order Task.
2. An OrderCreationView is displayed.
3. Create a new Order with a system assigned sequence number (order number).
4. Open the Order-Creation View using the new Order and display it to the user.
5. Perform the Find Customer in Context Task.
6. {Once, then repeat for each additional item} Perform the Add Order Item Task.
7. The user activates the Save command.
8. Inform the Create Order Task that the Save command has been activated.
9. The Create Order Task saves the Order.

Notice that although we've added a lot more procedural information (identifying the Customer, and so on), this narrative is actually a few steps shorter than the preceding one. We've done this by moving some of the detail (Add Order Item Task is an extract of steps 4 through 9 from the first version of the narrative) into another, new use case.

Another thing to notice is that this is just a little more abstract than a true story would be. Step 6 implies that at least one Order Item need be added but that a total of two or even more (we don't see a limit here) could be added. This could be broken into two or more narratives (one narrative showing the user adding one Order Item, and the second narrative showing the user adding three Order Items, for example).

There is one final way in which the immediately preceding narrative might be considered a bit too abstract. Detail like the number of Order Items but also like the Item Number and Quantity are completely missing. Some practitioners would write multiple narratives each representing various cases. Perhaps one would be a very normal example and another representing a boundary example (if the system only accepts up to 99 Order Items on an Order, a boundary example might try to add 100 Order Items). These would all be valid criticisms of the approach to narratives shown here. However, I find that the kind of brevity shown here makes it easier to evolve a set of narratives. Also, you (or a colleague) will have to capture this detail in either storyboards (to make the narrative come alive for the user) or test cases (to help QA know what they should be testing). Storyboards will often cover less ground than the narratives do as we'll see when we discuss them later this year. The test case base will, if anything, have to be more extensive than the narratives are and an approach to solve this problem will also be discussed later this year.

Scenarios Formalized: the Sequence Diagram

The following diagram depicts in a more formal way the content of the last narrative scenario. This is a UML sequence diagram. The boxes with vertical tails represent objects except for the very first box which represents the user and has a little stick figure icon in the upper corner of the box. As you scan down the diagram, you see horizontal lines with an arrow-head at one end. These lines represent events in the scenario's flow.

In this diagram, the user starts things off by requesting the start of the CreateOrderTask. At this point we make no assumptions about how this task is started; it might start as a consequence of some higher-order task activity of the user. This arrow goes straight to the task and is labeled with start. The CreateOrderTask must then do all of its startup activities: it creates an empty Order and it opens a OrderCreationView (at this point we only know it is a chunck of UI) displaying the empty Order.

With these first three steps we can see that some steps in the sequence diagram, such as steps 1 and 3, are steps visible in the narrative, while others, such as step 2, are details describing how the system sets itself up to respond to the user. Note, however, that even step 2 is couched in terms familiar to the user. This is additional detail not needed by the user but needed for completeness of the formal description.

The rest of the steps in the diagram similiarly represent the remainder of the narrative content.

The figure below is a sequence diagram showing the last narrative scenario formalized so that you can explicitly see the objects involved in the scenario and their interactions.

Figure: a UML scenario (sequence) diagram, over 650 pixels wide—click here to open it in a separate window.

Authoring Both Sequence Diagrams and Narratives

Ideally, the HCI practitioner would like both the informality and ease of reading of the narrative text for review with users, comparison with storyboard content, etc. However, the formal description is also useful. Though the details seen in the sequence diagram may seem tedious, they help assure that the scenario is complete and has not left out significant detail. When possible, it is my preference to author the narrative text as UML tagged values (these are just name-value pairs UML allows you to associate with the nodes and links on UML diagrams—if you can get tool support!) associated with the events shown as the horizontal lines terminating in an arrowhead. Given adequate reporting capability in a UML tool, you can then print both diagrams and the text-only narrative scenarios to show to users.