Skip to content
English
Contact us
  • There are no suggestions because the search field is empty.

How-to: Write a User Story (Needs Review)

What is a "User Story"?

User stories (also known as product backlog items "PBI) are short, simple descriptions of a feature told from the perspective of the person who desires the new capability, usually a user or customer of the system.

Anyone can write user stories! It's the product owner's responsibility to make sure a product backlog of user stories exists, but that doesn’t mean that the product owner is the only person who writes them. We expect to have user story examples written by all team members.

There are three main parts of a User Story that need to be present on each issue: summary, component, and description. 

Ticket Type Overview

  1. XD (X Dispatch): These tickets can be User Stories, Improvements, Bugs, Spikes, and Epics)

  2. CUS (Customer Support): These tickets can are used for reporting an issue to Engineering that you think is a bug, but may need to be investigated

  3. PM (Product Management): These tickets can be used for internal Product Department assignments and tasks.  Can be used for time logging for Customer and Internal meetings as well

  4. CSD (Customer Service Desk ): These tickets are for Technical Support

  5. PSD (Pro Services Service Desk ): These tickets are for Pro Services/Implementations.  These tickets are for new customer implementations and also for Customer Development Requests (CDRs)

  6. PRO (Pro Services Documentation ): These tickets are for Pro Services' Documentation request.

User Story Summary

The Summary of a User Story should follow a simple template: who, what, why

As a <type of user>, I want <some goal>, so that <some reason>

Types of users could be anything from the manager of a courier company, to an user of X Internet. We typically try to use some consistent language when writing user stories, but as long as anyone who looks up the ticket can easily understand who needs something, or who stands to benefit from a new feature, that's all we're looking to obtain.

"AS A USER," is NOT sufficient. What type of user? Give us a bit more detail.

The goal is what we want to have available to us when the project is complete. The engineering team needs to develop something. What are we asking them to develop? When they're complete, what new feature do we have available to us? 

The reason is arguably the most important part of the user story. What does the new feature offer us? Why is it important?  

Examples:

One of the benefits of user stories is that they can be written at varying levels of detail. We can write a user story to cover large amounts of functionality. If something is too large, we typically refer to that user story as an "Epic".

Here is an epic agile user story example from a desktop backup product:

  • As a user, I can backup my entire hard drive.

Because an epic is generally too large for an agile team to complete in one iteration, it is split into multiple smaller user stories before it is worked on. The epic above could be split into dozens (or possibly hundreds). For the epic above, we've broken it out into two user stories:

  • As a power user, I can specify files or folders to backup based on file size, date created and date modified.

  • As a user, I can indicate folders not to backup so that my backup drive isn't filled up with things I don't need saved.

     

More random examples of good user stories:

  •  As a Carrier Manager who uses credit limits with my customers, I want my CSRs to be able to view the credit limits that are set on customers on the order form, so that they do not have to navigate to the customer record to view this information.

  • As a Carrier Manager, I want X Internet end users to agree to changes in the terms of service upon their first sign in after the update to the TOS, so that I can prevent them from entering orders if they do not accept the new TOS.

  • As a Customer Service Rep who is working with X Route, I want to be able to print all of the shipping labels for Route Stop Parcels, so I can use these barcodes if the shipper does not print them or if the barcodes have been lost or destroyed. 

Examples of user stories that have room for improvement

  • As a user, I need an invoice export, so I can bill

  • As a manager, I want a report, so I can see what people are doing

  • As a customer, I want to put orders in, so someone picks up my shipment

User Story Components

You're asking the engineering team to build something. Help them identify where they're supposed to build it!

Typically if you're asking for us to build something inside X Dispatch, X Internet, or something that gets deployed when X Dispatch server is updated, the component is "X Dispatch". If it's not part of the release, but is a different part of our product suite, it should be listed: X Mobile, RapidShip, Nextstop Mobile, etc. 

If your user story is for an integration that we've worked on before, a component should exist. All of the integrations we have on the books begin with "Integration:" then the name of the shipping partner. "Integration: FedEx". There's a LOT of them though. JIRA has look ahead typing to help navigate through all of them. If you can't find the right one, leave it blank, and ask your team leader to have a component created for you.

If it's a custom project for a customer (custom invoice formats, custom pdf exports, customer specific integration modifications, etc) the component will begin with "Custom:". If we've done custom work for that customer before, the component will exist. If we have not, ask your team leader to have a component created for you. 

User Story Descriptions

The description of a user story is the detail of what they'll be working on. There are two major components of the description that must be on each user story:

Entrance Criteria

The purpose of the entrance criteria is to help the engineer understand the vision of what needs to be done. The engineering team often does not discuss requirements directly with whomever is requesting work to be done, and their mind reading helmet is still in beta. Our job is to help them understand the vision of the project. To transfer everything in our brains 

Everything that the engineer needs to know before starting work on a project should be written down here. Do not expect to put a ticket in, and have the engineer "come see me to get details." 

If you have pictures, wireframes, scanned documents, documentation, or anything else that pertains to the user story, it needs to be in the description.  

Our goal is to have the engineer sit down with the full set of requirements they need to complete their work, and have them work through it from start to finish without needing to track down requirements from people who may be (or more commonly are not) available to talk.

If you're asking the engineers to create an invoice format, explain how the customer intends to run the invoice. What it needs to contain. A mockup/picture of the end result as a attachment. If you're thinking "this might not make sense, but hopefully the engineer will understand what needs to be done", go back and rewrite the entrance criteria. 

Exit Criteria

Ok, so they've built something. Before an engineer can complete an issue, they must test it with the Project Manager. A good way to make sure that the requirements of the ticket are completed, and what you plan to test with them will work, is to just tell them what you'll be testing. 

Exit Criteria is simply what you plan to test with the engineer. If they're creating an invoice format, you'll want to test that it is correctly generated, and looks like what the customer gave to you. If you're adding new functionality, explicitly state what you consider to be a successful test.

Writing a User Story in JIRA

To create a JIRA issue, you need the Create Issue project permission for the issue's relevant project. If you do not have this permission, please contact your team leader.

To create a new JIRA issue:

  1. Click Create at the top of the screen to open the Create Issue dialog box.
    Check MarkKeyboard shortcut: c

  2. Select the relevant Project and Issue Type on the Create Issue dialog box.
    Check Mark Any issue that needs to be worked on by the CXT Engineering team needs to be entered in the "XD" Project. 

  3. Select the correct Issue Type. Typically you'll either be using one of two Issue Types:

    1.  

       Bug: A problem which impairs or prevents the functions of the product.

    2.  

       User Story: User stories (also known as product backlog items "PBI) are short, simple descriptions of a feature told from the perspective of the person who desires the new capability, usually a user or customer of the system. You just read about this, remember? 

  4. Type a Summary for the issue in User Story format, and complete any appropriate fields. Required ones are marked by an asterisk.

  5. Type a Description for the issue

    1. Descriptions must contain both entrance and exit criteria

Check Mark Tips:

  • You can mention other users in the Description or Comment field so that an email message will be sent to the user's email address (registered with their JIRA account) upon clicking the Update button. See Emailing an issue to users by mentioning them for details. 

  • In certain text fields for an issue, you can link to other issues, insert macros, insert images and more. For more information, see Editing Rich-Text Fields.

  • To see a list of all issues that you have created, which have not yet been resolved, go to your user name and select Profile and on yourprofile, click Filters > Reported & Open.

  • You may automatically become a watcher of the issues that you create, depending on the Autowatch setting in your user profile. Note, if you have not changed this setting, you will inherit the global Autowatch settings set by your JIRA administrator (in 

     > System > User Preferences). 

     

  • With appropriate configuration by your JIRA administrator, it is also possible to create issues via email.

  • If you are using agile Scrum boards for planning, you can easily add an issue to your backlog by using inline issue create.