Multipart article

How to Write a User Story in Software Development that Focuses on the User

Smartsheet Contributor Kate Eby on Jul 17, 2018

A risk that comes with software development is that end users find little value in the functionality you develop. But, there is a simple answer to that quandary: writing effective user stories before beginning development. The practical application of user stories provides a framework to identify user value by prompting conversations throughout the lifecycle of the software build. This article will explore what a user story is and isn't, how to write an effective story, and the importance of conversation over task lists.

Empathy is key to user story development process, and while many would argue it is easier to develop a list of requirements, the benefits of taking the time to understand your user is essential to delivering real value.

 

What a User Story Is and Is Not

User stories emerged as a result of Extreme Programming (XP), Kanban, and Scrum’s need to break down projects into smaller, incremental segments for sprints and iterations. They differ from use cases in that they focus on the smallest possible unit of work. Use cases, originally introduced by Ivar Jacobson, may be made up of several stories based on a common theme. The stories themselves are simple narratives outlining a single expectation or user goal. You can breakdown the creation of a user story into three stages:

  1. Describe the need.
  2. Plan the iteration.
  3. Implement and test the story’s completion.

At each stage, the user story can be refined to perfection.

User stories do not contain a requirements list or coding instructions, but will be associated with acceptance criteria or tests. The goal of a user story isn’t to focus on how to build, however. Instead, the focus is on who wants the feature, what it will do, and why it is important. Stories bring a human element to features that eventually make up the backlog activity to-do list.

Consolidate efforts. Synchronize sprints. Manage resources.

Agile Project Management Dashboard

Smartsheet is a cloud-based platform that allows teams and organizations to plan projects, streamline operations, and scale software development efforts. See Smartsheet in action.

 

Watch a demo


Why Are User Stories Important?

More than just a list of features, stories bring the user into the conversation. User stories provide context to software development by focusing on the value the user will experience. This people-first process mutes the language of Agile, allowing non-developers to collaborate and participate in conversations.   

User stories help facilitate constant dialog throughout the IT development project to aid in areas such as iteration/sprint planning and prioritizing the backlog for a release. By contrast, traditional Waterfall development embraces dialog at the beginning and the end of the development process.

In his book User Stories Applied for Agile Software, Mike Cohn of Mountain Goat Software says, “We make decisions based on the information we have at hand, and we do it often. Rather than making one all-encompassing set of decisions at the outset of a project, we spread the decision-making across the duration of the project. To do this, we make sure we have a process that gets us information as early and often as possible. And this is where user stories come in.”

 

Who Writes the User Story?

Product owners, stakeholders, product managers, and other business team members participate in writing user stories. Many will say, however, that who writes them is less important than who participates in the discussions and conversations that bring the stories to life. Start by identifying who will use the feature (the persona), which can be as detailed as needed. The user can be defined in terms of function or job description, such as student, frequent flyer, or marketing manager.

Having a strong understanding of the end user limits developer biases or assumptions. If the users are available, they can participate, but often the team has designers, managers, writers, and others who act as customer proxies. Participants may vary based on the usage of the user story. For example:

  • User Story Creation: Participants may include customers, product management, engineering, and other stakeholders such as HR, finance, and sales.
  • User Story Maintenance: Participants include product management or a product owner.
  • User Story Application and Usage: Participants include engineers/developers, technical writers, and quality assurance testers.

How to Write Effective User Stories

User stories are simple, one-line benefits statements of a valuable function. Prior to writing the user story, conduct user surveys and interviews to query the user about needed functionality. Start by writing a customer journey, stated in incremental stories, on 3x5-inch cards or Post-it notes. These cards can be put immediately into production or provide context for the backlog.

In the case of user story mapping, you can display Post-it notes along a conference room wall so the entire team can see it and work on long-range planning.

There are a few techniques you can use to help write the stories you need. A common technique is the Role-Feature-Reason or Benefit (RGB) structure that you construct by filling in the blanks of this sentence:

  • As a (user/persona/customer), I want to (do something) so that I will (receive a benefit).

Adding to the RGB question is a method pioneered by Ron Jeffries which highlights his “three C approach:”

  • Card: Write the answer to the RGB (described above) on the card.
  • Conversation: The limited detail on the card is the basis of a promise fulfilled by the second C. During this phase, the team discusses the details and establishes a definition of “done.”
  • Confirmation: This is the result of feedback that determines the test or acceptance criteria. This acceptance criterion is often written on the back of the card and is used as the initial checklist during future meetings to determine completion.

First introduced in an article by Bill Wake in 2003 and popularized by Mike Cohn’s book, User Stories Applied for Agile Software Development, the acronym INVEST is a method to evaluate user stories. INVEST criteria is as follows:   

  • Independence to develop in any sequence.
  • Ability to Negotiate the extent of the story to develop.
  • Provides Value to the user or business.  
  • Can be Estimated for completion.
  • Is Small enough to design, code, and test in a single iteration.
  • And finally, can be Tested.

Writing user stories that follow the RGB and three Cs methods are good starting points. Evaluating for effectiveness against INVEST goals keeps stories small, functional, and testable.

 

Bennett Lauber

Bennett Lauber, Chief Experience Officer with The Usability People, LLC, makes the following suggestions for someone preparing to write their first user story: “Make sure you do some research on your users and create personas. This will help the development team have empathy with the user.”

Agile User Story Template

Ready to write a user story? Download a free template to help you clearly define the feature from the end-user’s perspective. The template includes space for the type of user, what they want, and why they want it. By creating these short, one-sentence user stories, the development team can develop code that will satisfy the user story requirements. Find other useful Agile templates that you can download here.

 

Agile User Story Template

Download Agile User Story Template

Excel | Smartsheet

 

How to Write a Test Case from a User Story

A user story provides the guidance for developing tests or acceptance criteria. This checklist helps developers determine when the feature is done. As with all elements of user stories, the acceptance criteria is also written from the standpoint of the user. The test or acceptance criteria outlines the elements needed to successfully perform the required function.

This criteria should include the following:

  • The intended functional and non-functional requirements
  • Negative scenarios of the functionality
  • Performance guidelines
  • Proper user workflow
  • Impact to other features
  • User experience

 

Thomas Stiehm

Thomas Stiehm, CTO at Coveros, writes test cases using Gherkin Language. “This is the given, when, then (GWT) format,” he says. “I use test automation in Cucumber and that consumes Gherkin for automated testing. In addition, involving an experienced tester helps create better stories. They can ask important functionality questions while the story is being developed, which in turn results in more usable functionality.”

Let’s use a conference registration as an example test case: A user submits a form that includes their contact information, they choose a payment option, and a confirmation is displayed on screen and sent via email. These become part of the acceptance list. The test case also considers the ease and flow of the user experience (UX). Like the user story itself, the amount of detail tested reflects only what is necessary to ensure the feature delivers value.

 

Hernan Santiesteban

Hernan Santiesteban, of Great Lakes Web, shares his advice. “One of the best ways to write a test case is to use the given, when, then template, which establishes test conditions, user actions, and expected outcome. For example: given an administrative user signs in successfully, when the admin opens the user dashboard, then the admin will be presented with user management functions.”


Benefits of Writing Strong User Stories

To some product managers and development team member, writing user stories instead of requirements lists can feel like adding more steps to the overall Agile process. However, a key benefit of user stories is that they are collaboration-dependent and keep everyone informed and on the same page. Things can change during the development processes through discovery and stakeholder feedback — as a result, user stories can change or adapt to these circumstances.

Some of the most common benefits include the following:

  • Demonstrate progress quickly by breaking down the big picture into smaller projects.
  • Motivate the team and keep the project moving forward with quick successes.
  • Put the end-users first and thereby foster greater user acceptance and satisfaction.
  • Prioritize high-value features.
  • Provide the platform to have collaborative conversations that allow for creative solution planning.
  • Encourage high levels of cooperation that keep the team focused on outcomes that, in turn, create better overall products.

How to Write a Good User Story

It seems counterintuitive that the development of large software initiatives enjoys success and efficiency by going old school.  Simple 3x5 cards of varying colors and a permanent marker provide the humble basis for authoring user stories that bring context to an Agile development process. The small cards encourage basic benefits-driven descriptions that are discovered through team collaboration.

All user stories are unique and they should be complemented by story maps, diagrams, storyboards, and mockups, but below are a few best practices that can help you write an effective user story:

  • Know Your User: Define and understand your user persona(s).
  • Include All Stakeholders: Be sure to include all relevant stakeholders in the user story writing process. The testing team may even be able to refine the story.
  • Focus on the User: Discussions and conversations from the perspective of the user provide context and a definition of what constitutes “done.”  
  • Keep It Short and Simple: Describe only one piece of functionality in each user story. If a story is too big to be developed in a short period of time, break it down into smaller increments or create specific conditions can be added that limit the function. A good rule of thumb is that a user story should be small enough that the development team can complete it in one iteration.
  • Discuss and Collaborate: Discussions on project size, minimum viable product (MVP), who will use it, what it will do, and why it brings value all aid in decisions on inclusion and scope.
  • Avoid Technical Details: Don’t write technical tasks or “how to build” statements into the user stories as they may prevent creativity and collaboration. Technical details will come later in the process and be incorporated by developers, testers, and systems architects. A template can help guide away from technical details.
  • Focus on the 3 Ws:  Who will use it, what it is, and why it is important.
  • Encourage Visualization: Use whatever methods (drawings, story and impact mapping, storyboards, and mockups or prototypes) are appropriate to visualize the finished product. .
  • Clarify the Value and Benefit: Be sure the purpose of the story is clear, the urgency is noted, and the story is complete.

Challenges and Common Pitfalls of Writing User Stories

A user story answers questions such as who will use the feature, what the feature will do, and why the feature is important. The story’s details provide the business context, user value, and drive team discussions. A common challenge when writing user stories is ensuring that the story is comprehensive enough to articulate value, but simple enough to deliver in a short period of time, such as a sprint (which is generally between one and four weeks). The story should not contain technical details of how it will be built or coding instructions. These details are not needed at this point of development.

If a story is too big or too broad, it can be broken down into small parts.

Here is a good example:  

  • As a bank customer, I want to be able to see my balance, so that I can plan bill payments.

It may be tempting to add more detail or other functions, but that will create an unwieldy narrative. This kind of story would look something like this:

  • As a sales manager, I want to get my forecasting, sales, and personnel reports, so I can set my budget for an entire year.

This example has multiple components (generating individual reports: forecasting, sales, and personnel) that should be broken down into several smaller user stories.

In addition, be sure to include acceptance criteria, which identify what constitutes "done.” As noted above, acceptance criteria are often written as a checklist on the back of the user story card.

Additional challenges when writing acceptance criteria include the following:

  • The natural tendency to focus on how to build. However, leaving this technical detail out of the dialogue drives more meaningful conversations that lead to creative solutions, and also allows the inclusion of users and non-technical team members in the discussions.
  • Dialog and conversations can be time consuming and are often forgotten, which limits the positive impact of user stories.
  • Lack of data or a real understanding of the user or persona endangers the acceptance of functionality when put in the hands of the end user.
  • Limiting stories to the smallest increment is not easy, but too much detail makes the user story unwieldy.
  • Leaving out essential information, such as acceptance criteria or customer benefits, can leave questions unanswered during the development process.

Mike Cohn’s book User Stories Applied for Agile Software identifies the core problem in software development with this simple observation: “Software requirements is a communication problem.”

The technical language associated with software development and Agile methodologies can be a hindrance for many. Throughout the development process, writing user stories incorporate open dialog and conversations, breaking tasks down to keep momentum flowing, and providing strong definitions of done. Building software is a large-scale, time-consuming process with many stakeholders and high expectations. However, by following some simple guidelines and some old-fashioned techniques, the intricacies of building software become more visible to an entire team and, in the end, more doable. 


Master Writing User Stories with Smartsheet for Software Development

Empower your people to go above and beyond with a flexible platform designed to match the needs of your team — and adapt as those needs change. 

The Smartsheet platform makes it easy to plan, capture, manage, and report on work from anywhere, helping your team be more effective and get more done. Report on key metrics and get real-time visibility into work as it happens with roll-up reports, dashboards, and automated workflows built to keep your team connected and informed. 

When teams have clarity into the work getting done, there’s no telling how much more they can accomplish in the same amount of time. Try Smartsheet for free, today.

 

 

 

Discover why over 90% of Fortune 100 companies trust Smartsheet to get work done.

Try Smartsheet for Free Get a Free Smartsheet Demo