The Greatest User Story Ever Told

14 min readMar 29, 2020

User stories can be a great way to capture requirements for software development, but striking the right balance between simplicity and detail depends on understanding your goals, your organization’s culture, and the value user stories can provide.

Black design illustration with pencil on white paper

What Is a User Story?

In general, a user story begins as:

A short, simple, written description of a software feature or capability,
Expressed as a single interaction with the system from an end-user perspective, and
Used in an Agile software development process to capture and to begin to specify, discuss, and understand and ultimately to deliver and evaluate the result of a business or technical requirement.

User stories are often initially expressed in the form:

As a <user type> (aka user “role” or “persona”),
I want to (aka “require”) <some goal>
so that <some reason> (or “business value”) results.

An example of one of these simple, “summary-level” user stories might be:

As a Business Owner,
I want to define and manage my business’s location,
So that my business can be found easily by my customers and can better serve them.

This summary-level story can be thought of as a “mini mission statement” that should guide and bound further story development and detail.

Note: User stories are not the only way that requirements can be expressed. Many requirements management tools provide other issue types like tasks, subtasks (think boxes that must be checked in order to complete a task or user story), bug/defect reports, etc.

This article focuses on user stories, which describe system interactions from an end-user perspective.

Tasks are typically used to describe work that do not directly involve an end user but that must be completed in order to enable or facilitate these end-user system interactions. I sometimes refer to Tasks as “engineering directives” like “Install and configure a PostgreSQL database server … ”.

Since this type of work doesn’t involve an end user, trying to express Tasks as User Stories often results in tortured constructs like “As a Full Stack developer, I want to install and configure a PostgreSQL database, so that system information can be stored and retrieved”.

Selecting the appropriate issue type will make requirements easier to express and to understand and deliver.

Back to user stories …

We can write user stories at different levels of detail and at different times in the software development cycle. Demonstrating the principle of abstraction, a user story can describe a single small detail or cover what may ultimately be large amounts of functional or non-functional description at a much higher level, depending on the author’s intent or level of experience and on the story’s stage of development. Large user stories, which lack sufficient detail and/or are too big to implement in a single Agile process iteration, are generally known as “epics”, which need to be split (or “decomposed”) into smaller stories as each epic evolves.

Conceptually related user stories can be grouped or considered part of a “theme”, like “security” or “authentication”. This logical grouping is very similar to the practice of logically organizing source code using name spaces.

An actionable user story (one that is ready to be estimated, implemented, and delivered) describes a single interaction with the system, making it possible for software developers to focus exclusively on that interaction, sometimes referred to as a “vertical slice” of functionality, when a “full stack” developer implements the presentation layer, service layer, and data layer specified by a story. However, in many teams more specialized front end, service/API, database, and DevOps developers each follow a related but smaller and more focused user story in order to deliver their portion of the full, required functionality.

A user story often starts very simply (just a title or “headline”, like “Basic Location Management”) but then evolves to add detail, following certain specific conventions regarding its structure and content.

Branching foot path through trees with sign post

Why Do We Create and Manage User Stories?

User stories are one of the primary technical design artifacts of an organization’s Agile software development process. By documenting the “who”, “what”, and “why” of each requirement, along with acceptance criteria, in a simple, consistent, and concise way, they:

Communicate design intent in as much detail as necessary and with as little ambiguity and subjectivity as possible,
Encourage more in-depth and detailed analysis and design during the iterative process of creating the story,
Define the features and capabilities that a system must provide,
Enable estimation, prioritization, planning, and tracking,
Support testing and quality assurance (QA), and
Facilitate project and requirements management.

User stories should specify the features and functionality with which users will interact directly, like user interface (UI), business processes and rules, and data persistence and retrieval as well as “non-functional” business and technical capabilities that generally support the application and its users like required availability and performance criteria, system logging, and exception handling.

By capturing the detailed definition of a requirement, an actionable user story contains enough information to enable developers to reasonably estimate the relative effort required to deliver it, expressed in story points. Based on these estimates and considering the number of points the team has historically delivered per sprint (known as “velocity”), project stakeholders can make decisions about which stories should be delivered first (prioritized) and which should be deferred until later in the project. Keeping the total budgeted points for the project, current phase, epic, or theme in mind, stories may be simplified (or extended), or the team may be challenged to find more efficient ways to deliver the story for fewer points.

Because actionable user stories also contain detailed, specific, and objectively verifiable acceptance criteria, they establish the standard that the story will need to meet in order to be considered complete at the end of the sprint that includes it. These criteria:

Enumerate and clarify all relevant system preconditions, the nature of the interaction itself, and all relevant system postconditions,
Encourage developers to realistically consider the effort required for testing and QA and to include this effort in their estimates,
Suggest a minimum set of automated unit test cases that can demonstrate successful completion, identify defects and other issues, and prevent regression as the code base changes over time, and
Form the basis of test plans for formal QA and user acceptance testing (UAT).

And finally, in the context of a project plan that establishes a clear mission and specific, measurable, related objectives, user stories should provide “traceability”, clearly accomplishing the mission by supporting one or more objectives and one or more user personas. This traceability may be implemented with descriptive tags or labels that effectively group stories. User stories, including their revisions, comments, supporting documentation, etc, also establish a history of the project’s evolution and the team’s progress toward a better understanding of each requirement and project’s objectives and mission. At the end of the project the body of completed user stories should clearly establish the delivery of all business and technical requirements and the successful completion of the project.

Electric sign with arrows pointing right

Who Typically Creates and Manages User Stories?

The opportunity to create and manage user stories is often shared. While developers or “makers” may participate, most summary-level user stories are initially created and expanded by the product owner, business stakeholders, subject matter experts (SMEs), solution architects (SAs), and business analysts (BAs).

The product owner, who understands both business and technical concerns and whose focus is the planning and management of application features represent a very valuable perspective.
Because they know the business well and in many cases own or deeply influence it, business stakeholders are important sources of authoritative business requirements.
Subject matter experts with deep knowledge and experience of specific business domains and processes can make important contributions as stories evolve and become more detailed, especially to stories’ acceptance criteria.
Solution architects with deep knowledge and experience in the design and delivery of application software translate and express business requirements as technology structure and suggest and layer in cross-cutting technical concerns.
As business analysts move between strategic and tactical project levels, they acquire detailed, practical knowledge about requirements and the current state of the project and team overall.
And as they ask clarifying questions and challenge the understanding and assumptions on which many user stories are based, developers may indirectly contribute to story creation, evolution, and quality.

Pedestrian street crossing instruction sign

When Are User Stories Typically Created and Managed?

As appropriate for an Agile organization, user story creation and management typically happens iteratively throughout each project. Since we “write user stories at different levels of detail and at different times in the software development cycle”, it is probably more useful to discuss user story types and the project activities during which user stories, epics and user story themes are typically created, managed, and used.

User Story Types

User stories “can describe a single small detail or cover what may ultimately be large amounts of functional or non-functional description at a much higher level, depending on the author’s intent or level of experience and on the story’s stage of development”. Shorter, summary-level stories may not yet be “actionable”, i.e. ready to be accurately estimated or successfully implemented and delivered, but — whatever their state — they describe “a single interaction with the system, making it possible for software developers to focus exclusively on that interaction”.
Epics are “large user stories, which during their evolution are discovered to be too big to implement in a single Agile process iteration”. So, all epics are user stories, but not all user stories are epics. These large stories are often created early on in a project, while big and relatively undefined ideas are being captured. At this stage, they may be little more than “headlines”, e.g. “manage location and contact information”, which may be good candidates to consider for use as themes, e.g. “Location Information Management”, to be formalized, retained, and applied to group logically related stories that are created (or discovered) as the epic is further defined and split (or “decomposed”) into smaller, actionable stories.

Note: Investing the time to name stories well and to organize related stories using epics, themes, and tags can help to find them easily and to answer important questions about them later. Especially with longer projects, well-organized, detailed, and consistently and accurately-named user stories can provide an institutional memory of specifically how and why things came to be.

Project Activities

None of the user story-related activities below are exclusive to the project activities with which they are associated. The intent here is to associate the user story activities that typically occur during each project activity

Ideation/Requirements Gathering > Identify and Create User Stories and Epics. The focus during ideation/requirements gathering is capture. Capture should not impede the flow of ideas, so skip capitalization, good grammar, complete sentences, etc and get the gist — key words and ideas, sequence, dependencies, etc.
Backlog Grooming > Enhance, Prioritize, and Sequence User Stories and Split/Decompose Epics. Time set aside to groom the stories that have been captured in the backlog is essential preparation for Sprint Planning with the team. Splitting/decomposing epics into smaller user stories and adding detail, including acceptance criteria, relative priority, and logical, dependency-based sequence enables the team to quickly understand the goal(s) of the stories that are selected to make up the sprint in Sprint Planning.
Sprint Planning > Size, Assign, Prioritize, and Schedule User Stories. During sprint planning, the team discusses and quickly estimates the relative size of a number of the detailed, prioritized, and sequenced stories until the total number of story points approaches the team’s average velocity. These stories are scheduled in a sprint with a start and end date. The stories are assigned and may be re-prioritized based on team discussion or input from the product owner.
Implementation > Read, Identify, Create, Enhance, and Update User Stories and Split/Decompose Epics. Each story in the current sprint is read as a first step to implementing it successfully. Often other stories are identified, captured in the backlog, and enhanced with important detail as the sprint continues. And as each story progresses through its lifecycle, its status is updated, enabling the team to see its progress easily.
Testing > Read and Update (Accept or Reject) User Stories. During testing — by the developer, by a third-party tasked with ensuring quality, or by the product owner — each user story, especially its acceptance criteria, is read and used as the basis for accepting or rejecting it.
Delivering and Deploying > Identify, Create, Enhance, Read, and Update User Stories and Split/Decompose Epics. Delivery and deployment activities often bring still more user stories to light, and it is important to capture, define, quantify, and track this work to ensure that the team’s work is credited and accounted for comprehensively and accurately.
Supporting/Maintaining > Identify, Create, Enhance, Read, and Update User Stories and Split/Decompose Epics. Similarly, support and maintenance activities can identify other user stories — often software defects (or “bugs”) or enhancement requests.

Note: Support and maintenance stories are often completed in a continuous Agile process like Kanban rather than in an iterative Agile process like Scrum.

Feet in sneakers standing on a white arrow painted on a road surface

So What Does an Actionable User Story Look Like?

There are many ways to express user stories and many tools to manage and track them. One way of writing them that I can highly recommend based on years of success and thousands of stories is using Gherkin syntax. Yeah, like the pickle.

Gherkin uses keywords like:

“Feature”, where we can use our short, user story “headline”, e.g. “Basic Location Definition” and include our “As a … I want to … So that …” summary-level expression of the story,
“#” (comment),
“Background”, shared preconditions that are common to each scenario,
“Scenario”, a perfect place for describing the successful “happy” path and the “sad” paths or the ways the interaction may fail,
“Given”, this Scenario’s objectively verifiable preconditions,
“When”, this user story’s user-system interaction,
“Then”, this Scenario’s objectively verifiable postconditions

In Jira, we would duplicate the “Feature” text (“Basic Location Definition”) in the Summary field, and in the Description field we would see:

Feature: Basic Location ManagementAs a Business Owner,
I want to define and manage my business’s location,
So that my business can be found easily by my customers and can better serve them.# NOTE: See the “Location Management” screen mockup images attached below# NOTE: See the “StreetAddress Entity-Relationship Diagram (ERD)” diagram attached belowBackground:
Given I am currently logged in to the system, i.e. my browser has received a currently valid authentication token
And my business is represented by a record in the Organization database table
And I am currently on the "Manage Location" page for my business, conforming to the “Location Management” screen mockup image and specifications
 
Scenario: Successful Location Management
Given there are no records that represent my business location in the StreetAddress database table
When I submit (create/HTTP POST or update/HTTP PATCH) all required, valid StreetAddress data (e.g. StreetAddress1, StreetAddress2, CityName, StateId, CountryId, and PostalCode) to the system’s RESTful endpoint ‘example.com/api/v1/location'
Then this data is stored, along with system-generated and default data in a new or updated record in the StreetAddress database table, referencing my business record in the Organization database table
And a ‘201 Created’ or '200 Success' HTTP response is returned
And the new or updated StreetAddress entity data is returned in valid JSON format
And the new or updated StreetAddress data is displayed on the "Manage Location" page for my business, conforming to the “Location Management” screen mockup image and specifications
And this interaction is logged using the system’s existing structured logging features (available on stdout and stderr streams)Scenario: Unsuccessful Location Management Due to Invalid or Incomplete Data
Given there are no records that represent my business location in the StreetAddress database table
When I fail to submit (create/HTTP POST or update/HTTP PATCH) all required, valid StreetAddress data (e.g. StreetAddress1, StreetAddress2, CityName, StateId, CountryId, and PostalCode) to the system’s RESTful endpoint ‘example.com/api/v1/location'
Then the resulting exceptions are handled using the system’s existing exception handling features
And no database records are created or updated in the StreetAddress database table
And a ‘400 Bad Request’ HTTP response is returned
And no StreetAddress entity data is returned
And an "Invalid or Incomplete Data" error message is displayed on the "Manage Location" page for my business, conforming to the “Location Management” screen mockup image and specifications
And this interaction is logged using the system’s existing structured logging features (available on stdout and stderr streams)Scenario: Unsuccessful Location Management Due to Internal Service Error
Given there are no records that represent my business location in the StreetAddress database table
When I submit (create/HTTP POST or update/HTTP PATCH) all required, valid StreetAddress data (e.g. StreetAddress1, StreetAddress2, CityName, StateId, CountryId, and PostalCode) to the system’s RESTful endpoint ‘example.com/api/v1/location'
Then one or more unrecoverable exceptions occur in the StreetAddress service
And the resulting exceptions are handled using the system’s existing exception handling features
And no database records are created in the StreetAddress database table
And a ‘500 Internal Server Error’ HTTP response is returned
And no StreetAddress entity data is returned
And a "Temporary Service Error" error message is displayed on the "Manage Location" page for my business, conforming to the “Location Management” screen mockup image and specifications
And this interaction is logged using the system’s existing structured logging features (available on stdout and stderr streams)Scenario: Unsuccessful Location Management Due to Unavailable Service
Given there are no records that represent my business location in the StreetAddress database table
When I submit (create/HTTP POST or update/HTTP PATCH) all required, valid StreetAddress data (e.g. StreetAddress1, StreetAddress2, CityName, StateId, CountryId, and PostalCode) to the system’s RESTful endpoint ‘example.com/api/v1/location'
Then the StreetAddress service timeout is exceeded
And the resulting exceptions are handled using the system’s existing exception handling features
And no database records are created in the StreetAddress database table
And a ‘503 Service Unavailable’ HTTP response is returned
And no StreetAddress entity data is returned
And a "Service Timed Out" error message is displayed on the "Manage Location" page for my business, conforming to the “Location Management” screen mockup image and specifications
And this interaction is logged using the system’s existing structured logging features (available on stdout and stderr streams)

Note: The boldface and italics in the Gherkin user story above is for emphasis and clarity. This formatting is not necessarily supported or to be expected in Gherkin code.

Note: This user story is written at a “full stack” level, including objectively verifiable activity in each of the application’s implementation layers: presentation, service, and data. Some teams may prefer to split their stories into “front end” (user interface/presentation layer only) and “back end” (service and data layers) or presentation, service, and data layer stories. Whether and how to structure your user stories is a consideration based on your application’s technical structure, story size and complexity, developer skillset, story dependencies and sequencing, etc.

The Case for Clarity

Organizations that attempt to develop with nothing more than a headline (e.g. “Basic Location Definition”) or summary-level (e.g. “As a …”) user story in a rush to code will grossly underestimate their stories, will waste a great deal of time disagreeing about whether or not a story is complete, will suffer a high number of software defects, and will ultimately disappoint their business stakeholders and the organizations they serve.

Aided by the structure of the Gherkin syntax, the process of thinking through and writing clear, consistent, complete, actionable user stories with objectively verifiable precondition and postcondition criteria will serve you well. It requires discipline and time, but the time and other precious resources saved in the effort will much more than pay for itself.

Happy user story development!