User Story (Agile)

User stories define the applications, requirements, and elements that teams need to create. Product owners typically define and stack rank user stories. The team then estimates the effort and work to deliver the highest priority items.

You can learn how to fill in the details of a user story work item in this topic. The quickest way to create user stories is from the quick add panel on the product backlog page.

Required Permissions

To view a user story, you must be a member of the Readers group or your View work items in this node must be set to Allow. To create or modify a user story, you must be a member of the Contributors group or your Edit work items in this node permissions must be set to Allow. For more information, see Managing Permissions.

Defining a User Story

A user story communicates functionality that is of value to the end user of the product or system. Each user story should simply state what a user wants to do with a feature of the software and describe it from the user's perspective. When you write user stories, you should focus on who the feature is for, what they want to accomplish, and why. You should avoid descriptions that specify how the feature should be developed.

The work item form for a user story stores data in the fields and tabs that the following illustration shows:

When you define a user story, you must define the Title in the top section of the work item form. You can leave all other fields blank or accept their default values.

To define a user story

1. In Title (Required), type a short description.

   Good story titles reflect the value to the customer or functionality that needs to be implemented.

2. In the right section of the form, specify the following information:

   • In the Assigned To list, choose the name of the team member who owns the user story.

     Note

     This list is auto-populated with the names of all accounts that have been added to the team project.

     If you leave the story unassigned, it is automatically assigned to you.

   • In the Story Points box, type a number that specifies a subjective rating for the amount of work that will be required to complete a user story.

     If you specify more points, you indicate that more work will be required.

   • For Risk, choose the value that represents the relative uncertainty around the successful completion of the story.

   • Leave the Stack Rank value as is. This field captures the value used to stack rank items on a backlog page.

   • For Area and Iteration, choose the appropriate area and iteration paths or leave these fields blank to be assigned later during a planning meeting.

     Note

     The project administrator for each team project defines area and iteration paths for that project so that the team can track progress by those designations. For more information, see Create and Modify Areas and Iterations.

3. On the DETAILS tab, provide as much detail as you want to describe not only the user story but also the criteria that you will use to verify whether the user story has been fulfilled.

   Your team will use this information to create work items for tasks and test cases. For more information, see Task (Agile) and Test Case.

4. On the HISTORY tab, add comments that you want to capture as part of the historical record.

   Every time that a team member updates the work item, its history shows the date of the change, the team member who made the change, and the fields that changed.

5. (Optional) Link the user story to other work items, such as tasks, test cases, bugs, and issues as described in later sections in this topic.

6. Choose Save Work Item.

Adding and Linking Tasks to a User Story

You add tasks to a user story to track the progress of work that has occurred to complete the user story.

To create a task that is linked to a user story

1. On the Implementation tab, choose New.

   

2. In the Link Type list, leave the default option, Child.

3. In the Work Item Type list, choose Task.

4. In Title, type a name that identifies the area of work to be performed as specifically as possible.

5. (Optional) In Comment, type additional information.

6. Choose OK when done.

   A work item form for a task opens with the information that you have provided.

7. Specify the remaining fields as described in Task (Agile), and then choose Save Work Item.

To link several existing tasks to a user story

1. On the Implementation tab, choose Link to.

2. In the Link Type list, leave the default option, Child.

3. Choose Browse.

   

4. Type the items in Work item IDs, or browse for the items to which you want to link. You can also run the My Tasks team query to locate the tasks to which you want to link. Select the check box next to each task that you want to link to the user story. For more information, see Find Work Items to Link or Import.

5. (Optional) Type a description for the tasks to which you are linking.

6. Choose OK, and then choose Save Work Item.

   Note

   Both the user story and tasks that you linked are updated. A parent link to the user story is created for each task that you added.

Adding and Linking Test Cases to a User Story

As part of planning, you create test cases and link them to user stories. The recommended client for creating test suites and test cases is Microsoft Test Manager. From this client, you can also link to a user story as described in How to: View Product Backlog Items, User Story, or Requirements Work Items Using Microsoft Test Manager.

To add a new test case to a user story

1. On the Test Cases tab, choose New.

2. In the Link Type list, leave the default option, Tested By.

3. In the Work Item Type list, leave the default option, Test Case.

4. In Title, type a descriptive name that defines the area to be tested.

5. (Optional) In Comment, type additional information.

6. Choose OK.

   A work item form for a test case opens with the information that you have provided.

7. Specify the remaining fields as described in Test Case, and then choose Save Work Item.

To add existing test cases to a user story

1. On the Test Cases tab, choose Link to.

2. In the Link Type list, leave the default option. Tested By.

3. In Work item IDs, type the IDs of the test cases that you want to link, or browse for them.

   You can run the My Test Cases team query to locate the test cases that you want to add, and then select the check box next to each test case to which you want to link. For more information, see Find Work Items to Link or Import.

4. (Optional) Type a description for the test cases to which you are linking.

5. Choose OK, and then choose Save Work Item.

   Note

   Both the user story and test cases to which you linked are updated. A Tests link to the user story is created for each test case that you added.

Adding an Issue to a User Story

You can create a work item for an issue and link it to the user story from the All Links tab. By defining the issue and linking it to the user story, you can better track the quality and completion of the user story.

To create an issue and link it to a user story

1. On the All Links tab, choose New.

2. In the Link Type list, choose Related.

3. In the Work Item Type list, choose Issue.

4. In Title, type a name that identifies the blocking issue as specifically as possible.

5. Choose OK.

   A work item form for an issue opens with the information that you have provided.

6. Define the remaining fields as described in Issue (Agile), and then choose Save Work Item.

Adding Details, Files, and Hyperlinks to User Stories

You can add details to user stories in the following ways:

• Type information in the Description or History field.

• Attach a file.

  For example, you can attach an e-mail thread, a document, an image, a log file, or another type of file.

• Add a hyperlink to Web site or to a file that is stored on a server or a Web site.

To add details to a user story

1. On the Details tab, type information in the Description field.

2. (Optional) Type information in the History field.

   You can format information to provide emphasis or capture a bulleted list. For more information, see Titles, IDs, Descriptions, and History Field Reference.

3. Choose Save Work Item.

To add an attachment to a user story

1. On the Attachments tab, perform one of the following actions:

   • Drag a file into the attachment area.

   • Choose or press CTRL-V to paste a file that you have copied.

   • ChooseAdd, and then click Browse. In the Attachment dialog box, type or browse to the name of the file that you want to attach.

     (Optional) In the Comment box, type more information about the attachment. To return to the Attachments tab, choose OK.

2. ChooseSave Work Item.

To add a hyperlink to a user story

1. On the All Links tab, choose Link to.

   

2. In the Link Type list, choose Hyperlink.

3. In the Address box, type the address of the target of the link.

4. If the target is a Web site, type the URL, or copy it from your Internet browser and paste the URL into the Address box. If the target is a server location, type the address in the form of a UNC name.

5. (Optional) In the Comment box, type more information about the hyperlink.

6. Choose OK, and then choose Save Work Item.

Workflow

You can use the New, Active, Resolved, and Closed states to track the progress of user stories. When you have written the code to implement a user story and all unit tests have passed, you change the State of the user story to Resolved. After all tasks are completed and the user story passed all acceptance tests, you change its State to Closed. Any team member can change the state of a user story.

For more information about the data fields that you can use to track work item states, see Assignments and Workflow Field Reference.

Typical workflow progression: A customer representative creates a user story in the New state with the default reason, New. A team member changes the state of the user story from New to Active when the implementation has been started. A team member changes the state of the user story from Active to Resolved when it is code complete and unit tests have passed. A team member changes the state from Resolved to Closed when the test cases that were defined for the user story have passed.

User Story State Diagram

See Also

Concepts

Storyboard backlog items

Other Resources

Building and Managing the Product Backlog

Agile Process Template for Visual Studio ALM

Plan the Sprint

Work Items and Workflow (Agile)