Have you ever found it challenging to communicate to a developer what you are wanting them to do? Or got to the end of a project only to realize that you were asking for one thing and got something totally different? We understand the challenge of how clear communication is vital to the success of your project or support ticket, but communicating technical needs is inherently difficult.

Luckily, we have discovered that user stories help make it easy for merchants to communicate clear instructions to developers about their needs, regardless if you have any technical knowledge or not. User stories allow you to provide the developer with the insights they need to extract technical requirements and other things they need to make it happen.

What are User Stories?

User stories describe the end user’s needs through various perspectives and scenarios. A user story starts with a particular user role and then goes through each use case (scenario) for that type of user. User stories make it easier and more efficient for you to communicate the necessary information a developer needs without being technical or trying to list out specific tasks.

Writing a User Story

Writing a user story is easy. Simply think of the different user types on your site and what things each group needs to be able to do on your site and for what reason(s). The end goal of a user story is to provide the necessary information for a developer to extract business and technical requirements while eliminating hidden assumptions. Below is a simple templated format that you can use for your next project or support ticket request:

Formatting User Stories

User stories usually consist of three types of information. You have the individual user stories, the acceptance criteria for when the task is complete, and any technical notes that might be useful for the developers to know. If you don’t have any technical notes, not to worry. The user stories and acceptance criteria are enough to get the developer started.

Individual User Story Template & Examples

There is an underlying template in most all user stories that you will use:

As a [user type], I want to [function] so that [benefit].

The [user type] makes sure you are thinking about who will use this feature. If there isn’t an identifiable customer for the feature, you should reconsider whether you need it.

The [function] describes what will happen, but not *how* it will happen. User stories are designed to start a conversation within the team about the best way to make this feature.

The [benefit] describes the ultimate purpose of the feature. If you can’t think of an achievement, that’s a signal that you should reconsider whether the feature you’re trying to describe is actually important.

Examples of User Stories:

  • As a consumer, I want shopping cart functionality so that I can easily purchase items online.
  • As an executive, I want to generate a report on which product categories generate the most revenue so that I can decide on which product categories to focus on.
  • As an administrator, I want a report of all out of stock items with the names of customers that asked to be notified when the product is back in stock, so I can communicate to them when it’s back in stock.
  • As a customer, I want to be able to see how much more I need to add to the cart to qualify for free shipping.
  • As a marketing tech, I want to be able to see the click-through-rate on our home banners so that I can improve the effectiveness of the banner over time.

How to Write Acceptance Criteria

The second part of user stories is acceptance criteria, which is where you provide details for the developer to know what you expect to be delivered in order to solve the issue. The acceptance criteria will form the foundation of any tests that will confirm that a new feature, fix, or piece of functionality is working as expected and is complete. Providing acceptance criteria will help ensure that the developer has the end in mind before the project or support ticket is even started. Providing this info will help the developer get started faster on solving the issue and likely reduce the time it takes to complete the task, thus saving you money on development hours.

If you are not sure on a solution, you can mention that you are open to suggestions. In fact, developers inherently love to solve problems, so collaborating with them may produce a better end result. Still be sure to give them as much detail as you can on what needs to be done to accept the work as complete. Acceptance criteria are written in simple language, just like the user story. Below is an example to help you write your own:

Example of Acceptance Criteria

We are wanting a way to make it where Customers will have a notification that lets them know how much more they should spend while shopping and during checkout to receive free shipping. Free shipping is applied when a customer has $50 or more in their cart.We'd like to display a banner at the top of the page that says “You’re only XXX away from Free shipping!” so the customer knows how much more they should spend to qualify for free shipping no matter what page they are on. Please see attachment for a design example.

Writing (Not so) Technical Notes

Technical notes are not all that technical (generally speaking), they are just extra bits of information that may aid the developer and technical team in completing the task. This could include any due dates that you are needing this completed by, any existing functionality that the developer might need to be aware of, or any special credentials that the developer might need. Note: For security reasons, please do not send passwords in the tickets. If a developer needs credentials to something they will schedule a call to get that information

Examples of Technical Notes:

  • We need this done by October 30th, so we can be ready for the Holiday Season.
  • We use this [extension name] for managing rules for shipping.
  • Payment gateway is configured as such… [include configuration explanation]
  • Our current workflow is as follows… [include your workflow that relates to the task]

Using Multiple User Stories for One Support Ticket or Task

A support ticket can have multiple user stories if they are affecting multiple types of users, or some users experience a different benefit.

Example of using Multiple User Stories for a task

    Task: Add in-stock email notifications for products
  • As a customer, I want to be able to know when a product will be back in stock.
  • As an admin user, I don’t want to have to manually email clients when an item is back in stock. I want it to be automatic.
  • As a customer analyst, I want to see a report on all the emails that have signed up for a notification when a product is in stock.

Tips for Better User Stories

  • Try to avoid the use of “User” when saying “As a user…” Instead use specific details like “Customer”, “Administrator”, “Customer Service Representative”.
  • Make sure to include the benefit so that a developer can understand why this function is important, and what it needs to do. If you have trouble defining a benefit, then you should reconsider whether or not you actually need this specific user story.
  • Make sure that your acceptance criteria are as complete as possible, so that at the end of a ticket, we can go back to the original post and make sure it functions just as the acceptance criteria define it.

Complete User Story Examples

Example 1

User Story: As a customer I'd like to be able to know how much more I need to spend to qualify for free shipping so that I can possibly add a few more products to my cart and get the free shipping.

Acceptance Criteria: We are wanting a way to make it where Customers will have a notification that lets them know how much more they should spend while shopping and during checkout to receive free shipping. Free shipping is applied when a customer has $50 or more in their cart.We'd like to display a banner at the top of the page that says “You’re only XXX away from Free shipping!” so the customer how much more they should spend to qualify for free shipping. Please see attachment for a design example.

Technical Notes: Free shipping is applied when a customer has $50 or more in their cart.

Please give me an update if this is going to take more than 4 hours of development. Thank you!

Example 2

User Story: As a customer, when I place an order that gets flagged for suspected fraud, I receive a notification about it, but I don’t ever receive any information on when to expect the items to be shipped.

User Story: As an administrator, we don’t see the order because it is not in processing. I want to be able to access it easily so I can quickly take care of approving or denying the order so it doesn’t just sit there forever.

Acceptance Criteria: We want to make an area in the admin that we can easily see all suspected fraud orders. We also want to automatically inform the customer via an email that their order is under review. We also would like a sticky notification that stays at the top that lets us know if we have any orders that are suspected fraud so we are sure to review them as it is important for us to get them processed or decline them. The sticky notification would look similar to the cache management notification, and have the current number of orders displayed that need fixed. For examples. “You have (x) order(s) that are suspected fraud.” When you click on the notification it takes you to the list of orders.

Technical Notes:

    Our current workflow for incoming orders.
  • Order is placed and Magento flags as suspected fraud
  • If we notice the suspected fraud, we will most of the time reach out to the customer
  • If we didn’t notice the suspected fraud, it sits forever in this suspected fraud status.
  • Communication with client back and forth.
  • If we approve, we will mark the order as approved and prepare the shipment and complete the order
  • If we do not approve, we will mark the order as not approved and the order will be voided.

Example 3

User Story: As an administrator, I don’t want to ship certain products to Alaska.

User Story: As a customer: I want to be able to know that that certain product does not ship to Alaska before adding it to the cart.

User Story: As a customer, when I add several products in the cart and try to checkout. If I select an Alaskan address and get an error that I have a product in my cart that doesn’t allow being shipped to Alaska, I would like to know which product that is so I can quickly identify the problem and remove it from my cart so I can still purchase the other items.

Acceptance Criteria: We need to create an option in the edit product area for specific products to not be shipped to Alaska. So when a customer tries to add a such a product to the cart, it will let them know. We want the product details page to display that it does not ship to Alaska. When the item is placed in the cart, we would like an alert notification to display, letting the customer know that the item in their cart does not ship to Alaska. The checkout process will need to reject shipping the item to Alaska, and give an error that explains what product in their cart is causing them not to be able to ship.

Technical Notes: We have Webshopapps Shipping Override II as part of the Commerce package we purchased. We have Shipping Overrides set up and Special Shipping Groups are assigned to our products. This has been functioning fine, however, now it is not consistent.

Needing Developer Support for Your Magento Website? Sign up today risk free!