Adding Requirements

The next step is to start defining requirements for the online bookstore. We will start by defining a user activity; in this case the user activity is visiting the online store’s home page.

Note: Depending on your preferred methodology, you may want to define additional requirements, such as business goals, actors, impacts and deliverables. For the purpose of this tutorial, we will limit our project to user activities and user stories. However all requirements are added and managed in the same way, so these steps apply equally to all types of requirements. For more information on agile development methods, we recommend reading Impact Mapping and Specification by Example by Gojko Adzic.

Adding a User Activity

A user activity represents an activity that can be performed by a user of the system. Our first user activity is visiting the bookstore's home page. A user activity consists of two fields: one for the actors that can perform the activity and one to store the goal of the activity. We will assume that there will be two types of users of the system, standard users (“customer”) who are limited to ordering books, browsing the shop etc. and VIP customers who have additional options available (e.g. add a wishlist, write reviews, receive loyalty discounts).

To add a new user activity:

1. Double-click on User Activity in the New Requirement widget, or drag the User Activity entry in the widget to the desired location on the workspace.
   Note: If you can't see the widget, click on New Requirement at the bottom of the screen next to the menu icon to display the widget.
2. Click on the new requirement and enter the actors in the Actor field. Accessing the home page can be performed by both customers and VIP customers, so enter “Customer, VIP Customer” here.
   Note: To navigate in the workspace, click on the workspace and drag the mouse to scroll, and use the mouse wheel to zoom in and out. Click and drag an element to reposition it. You can also navigate using the Navigator widget.
3. Enter the user activity in the second field (you can navigate between fields using the Tab key), e.g. “Visit the home page”.
   /ScreenShots/GettingStarted/GettingStartedUA1.png
4. Add additional user activities in the same manner to represent other activities that can be performed by the users (some activities are only available to VIP customers), e.g.:
   /ScreenShots/GettingStarted/GettingStartedUserActivities.png
   (click here to view the full size image)
   In this case, the flow from left to right represents the general order in which users will perform specific tasks. You can of course structure your workspace according to your own needs.

Adding a User Story

In the next step, we break down (refine) our user activities into user stories. These user stories should be linked to their parent user activity card to illustrate their relationship.

To add a user story as a refinement linked to a parent card:

1. Drag the User Story element from the New Requirement widget to the “Visit the home page” user activity card you added in the previous step. Once the user story is over the card, “Drop card here to link as refinement” is displayed. Drag the user story to this box until it changes to green and release the mouse button to add the user story as a refinement (child).
   Alternatively, you can select the user activity card and use Ctrl+N to add a user story that is linked to the selected user activity.
2. Drag the new user story to a suitable location on the workspace. You should see an arrow linking the user story to the parent user activity card:
   /ScreenShots/GettingStarted/GettingStartedUAUS.png
3. Enter the following details in the user story:

• As a Customer, VIP Customer
• I want to see the cheapest books
• So that I can get a good bargain

1. Click on the Estimate field in the bottom right corner of the card, and enter an estimate for the user story, e.g. “2”:
   /ScreenShots/GettingStarted/GettingStartedUS7Estimate.png
   The estimates of the total effort required for all requirements is displayed at the top of the workspace:
   /ScreenShots/GettingStarted/GettingStartedTotalEstimate.png
   Note: How you define estimates is up to you, as they are not defined using a particular unit. You can choose to use whatever unit suits your project (e.g. person days), or simply enter a value that indicates the relative complexity of a particular requirement.

Repeat this process to add additional user stories to your user activities. Continuing the previous example, you might want to add the following user activities:
/ScreenShots/GettingStarted/GettingStartedFullBoard.png (click here to view the full size image)

Note: You can download the final project here.

In this example, requirements are ranked by priority from top to bottom. You can of course structure your project according to your own method and requirements.

Defining Acceptance Criteria

Now that you have added your user stories, you can define acceptance criteria for your user stories. We will proceed to define acceptance criteria for the “see the cheapest books” user story.

To do so:

1. Double-click on the title of the user story (“see the cheapest books”) to open the requirement details.
2. Click on ADD CRITERION in the header on the right of the screen.
   A new criterion is added to the user story. Acceptance criteria consist of two fields:

• A single-line title.
• A multi-line body.

1. Click in the first field and enter a title for the acceptance criteria, e.g. “Display 5 cheapest books”.
2. Click in the second field and enter a description of the acceptance criteria, e.g. “Sort books by price (cheapest first)”.
3. Repeat the process to add additional acceptance criteria, such as “Include hyperlinks to book page”, “Display relevant information on books” and “Display placeholder if no thumbnail is available”:
   /ScreenShots/GettingStarted/GettingStartedAcceptanceCriteria.png
   Note: You can also add files to acceptance criteria as attachments and link acceptance criteria to Gherkin files.

Requirement Tags

To make it easier to find related requirements at a later time, you can assign tags to requirements. When searching for requirements in the Requirements widget, any requirements containing matching tags are returned by the search.

1. Open the requirement details view for the “see the cheapest book” requirement (the view should be open already unless you switched views in the meantime).
2. Enter “Discuss with client” in the requirement’s TAGS field to indicate that this business goal still requires discussion:
   /ScreenShots/GettingStarted/GettingStartedTags.png
   You can enter multiple tags separated by a comma.
3. Open another requirement card, either by clicking on an entry under Other Similar Requirements in the requirement details, or by double-clicking on the card on the workspace. Enter the tag “Approved by client”.
4. Click on Requirements in the toolbar at the bottom of the screen to open the Requirements widget.
5. Enter “client” in the search box. Both requirements are listed, as both of them have a tag containing the term “client”.
   /ScreenShots/GettingStarted/GettingStartedRequirementSearch.png
   Note that the total effort for the requirements returned by the search is also displayed in the widget.
6. Enter “Discuss” in the search box. Only the first requirement is listed.
   Note: The search returns all requirements where the search term is entered in one of its fields, acceptance criteria or as a tag. If you search for “customer”, all requirements are returned, as they all include “customer” in one of the fields. You can restrict the search to specific elements using query expressions.

Previous | Next