The Greatest User Story Ever Told

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,

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​ be able to define and manage my business’s location, contact information, and operating hours,
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.

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,

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,

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​.
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”.

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.

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,

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 DefinitionAs a Business Owner,
I​ want to​ be able to define my business's location,
so that​ my business can be found easily by my customers and can better serve them.
#
# NOTE: See the “StreetAddress ERD” below
#
Background:
Given My business is represented by a record in the Organization database table
And I am currently logged in to the system, i.e. my browser or HTTP client application, e.g. Postman, has received a currently valid authentication token from the system
Scenario: Successful Location Definition
Given there are no records that represent my business location in the StreetAddress database table
When I POST all required, valid StreetAddress data (StreetAddress1, StreetAddress2, CityName, StateId, CountryId, and PostalCode) to the system’s RESTful 'example.com/api/v1/location' endpoint
Then this data is stored, along with system-generated and default data in a new record in the StreetAddress database table
And a ‘201 Created’ HTTP response is returned
And the new StreetAddress entity data is returned in valid JSON format
And this interaction is logged using the system's existing structured logging features (available on stdout and stderr streams)
Scenario: Unsuccessful Location Definition 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 POST all required, valid StreetAddress data to the system’s RESTful 'example.com/api/v1/location' endpoint
Then 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 ‘400 Bad Request’ HTTP response is returned
And no StreetAddress entity data is returned
And this interaction is logged using the system's existing structured logging features (available on stdout and stderr streams)
Scenario: Unsuccessful Location Definition Due to Internal Service Error
Given there are no records that represent my business location in the StreetAddress database table
When I POST all required, valid StreetAddress data to the system’s RESTful 'example.com/api/v1/location' endpoint
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 this interaction is logged using the system's existing structured logging features (available on stdout and stderr streams)
Scenario: Unsuccessful Location Definition Due to Unavailable Service
Given there are no records that represent my business location in the StreetAddress database table
When I POST all required, valid StreetAddress data to the system’s RESTful 'example.com/api/v1/location' endpoint
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 this interaction is logged using the system's existing structured logging features (available on stdout and stderr streams)

Note: This user story is written at the system’s API/service level. Other related stories might describe the user interface and database levels.

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!