Modeling user stories

Your team can create models that help it understand the user stories that it is about to estimate or develop. Your team can also use models in ongoing discussions with your product owner that occur during development, if the questions are adequately complex.

For example, your project may involve a set of concepts that are new to your team. By working with your product owner, your team can develop a domain class diagram to capture these concepts and the relationships between them. If your team must understand the major sequences in a user activity, it can create an activity diagram.

For more information, see Modeling User Requirements.

The Domain Model: The Users' Language

Domain class diagrams

A domain class diagram shows the concepts and relationships that are associated with the application. Everyone who is associated with the application can then use those concepts to achieve more consistent understanding.

The example in the previous illustration is not directly a class diagram of the software solution, which might represent these relationships in several different ways. Instead, it presents a vocabulary with which you can write the user stories:

The customer chooses a Menu from which to construct an Order, and then the customer creates Order Items in the Order by selecting Menu Items from the Menu.

Because it is a model of concepts instead of objects in a program, you ordinarily do not assign operations to the classes when the diagram is used for this purpose. Instead, you can use activity diagrams to describe the actions that the users perform.

For more information see UML Class Diagrams: Guidelines.

Activity diagrams

Your team can explain the flow of activities that a user can perform and show the alternative courses of action at each point by using activity diagrams.

When your team creates tests, it can refer to activity diagrams and create a test for each path through the activity diagram.

A user story might introduce a path in an existing activity diagram. For example, a user story might be "As a customer, I can choose to save an order for later instead of paying for it now." When the story is taken into a sprint to be developed, the activity diagram can be updated to express the new feature.

The activity diagram can describe a complete set of paths that the user can follow by using a particular release of your application, if you update the diagram to reflect all user stories that your team has implemented.

For more information, see UML Activity Diagrams: Guidelines.

Using the model to uncover gaps

Your team can better understand the requirements of your users by avoiding misunderstandings that occur in conversations that are not supported by a diagram. For example, a diagram would clearly distinguish between an item on an order and an item on a menu.

Creating the model helps your team ask questions that it might not otherwise ask until much later in development. Some techniques include the following:

• Asking about the cardinalities on a class diagram (for example, "Can a menu item appear on more than one menu?").

• Asking about loops in the class diagram (for example, "In any order, are all items from the same menu?").

The answers to these types of question can be added as comments on the diagram.

Model consistency

Your team can resolve ambiguities by making sure that the model and user stories are consistent:

• The user stories use the terms that are defined in the model and are consistent with the relations that it defines. If the model defines menu items, the stories should not use the term "products" to mean the same thing. If the class diagram shows that a menu item belongs to exactly one menu, the stories should not refer to sharing an item between menus.

• Every user story describes a series of steps that is allowed by the activity diagrams.

• User stories or activities describe how each class and relationship on the class diagram is created and destroyed. For example, what user story creates a menu item? When is an order destroyed?

Models and the Product Backlog

Your team can mark models and storyboards to show what parts will be changed by each user story and can color or comment on a model to help you plan the development. For example, your team could color the actions in an activity diagram to indicate which ones have been completed and which will be completed in the next sprint.

For more information, see Modeling User Requirements.

Models and Tests

Your team can use a domain model as a basis for system tests, which makes a clear relationship between the tests and the requirements of the users. This relationship helps your team update the tests quickly and correctly and helps make sure that the product meets the new requirements.

Your team can link any element in a Unified Modeling Language (UML) model to any work item, such as a test. When any part of the model changes, the model will help your team locate the tests to which it is related.

Use the domain model to help you create tests:

• Create at least one test that involves the construction of each type or association, such as menu item or order item, and at least one test that involves its destruction.

• Make sure that all paths that are described by activity diagrams are tested.

  Note

  The tests should also cover exceptional paths that you would not ordinarily illustrate in activity diagrams.

• Use the vocabulary of the domain model to define the tests. For example, your tests would include a test of the Select Menu Item action, which would verify that the action results in the Order containing a new Order Item. To write automated tests, you can use classes and relationships that are based directly on the diagram.

For more information, see Developing Tests from a Model.