Below is the template I created for writing user stories.

# User Story

As a...  
I want...  
So that...  

# Description

Lorem...

# Acceptance Criteria

- bullet criteria

GIVEN setup  
WHEN action  
THEN result  

I write a lot of user stories for my team, and they need to be clear, to the point, and verifiable. This template was born out of a need for consistency in how user stories were defined and written and aims to give a development team the bare minimum they need to deliver a hot, fresh slice of valuable software. Nothing here is ground-breaking, but it serves as a foundation for defining work when building software.

User Story Statement Section

First, we start with the traditional user story statement.

As a
I want
So that

This forces the author of the story to be clear about who wants what, and most importantly, why they want it.

For the As a clause, try to be clear about a specific type of person. If your description can conjure up a mental picture of a distinct archetypal user-type, you’re doing it right. Avoid writing simply As a user at all costs. We’ve all done it, and we should all be ashamed.

In your I want section, describe one want. If you are tempted to have more than one clause here, you might consider if an additional user story is warranted.

With the So that clause, focus intently on the unique value this will provide to your archetypal user-type. This is the hardest clause to write, but also the most important to do well. It’s value may be obscure to some, because it does not directly contribute to the “spec” of what needs built. But this is your chance to clearly define the impact of this work to be done. It breathes life into the code to be written, and gives your designer, developer, tester, etc. a clear reason for doing what they’re doing.

Description Section

This is your chance to go into more detail about your user story. What should the user-facing phrasing be? What data are we working with?

I often will take a first pass at this providing as much important context and detail as I can from the product perspective. Sometimes, a developer will go into description after I’ve written it and add a subsection for Technical Details to go more in depth on any technical nuances to the user story that should be considered during development and testing.

Acceptance Criteria Section

Acceptance criteria gives the team a clear basis to know when they are done with a user story. It is something we can point to and either say “Yes, we accomplished what we wanted to” or “No, this doesn’t do everything we needed”.

I write acceptance criteria one of two ways, and sometimes I use both.

Bullet Syntax

Acceptance criteria can be a simple bullet-list. This is more often the case for smaller user stories, or ones that are more technical. This can be a simple, useful tool to include any non-functional requirements that need to be met to accept the user story.

Gherkin Syntax

When it makes sense, I write acceptance criteria in GIVEN, WHEN, THEN format. This lays out a very clear path for manually testing the user story, and this syntax can be used for behavior driven development. It becomes an executable spec that we can use directly in our automated tests.

Example

Here’s an example of a user story I’ve written recently:

User Story

As a case owner or admin
I want to add users to my case
So that I can collaborate with others
And determine appropriate access levels for CRUD operations

Description

link to mockups

The scope of this ticket includes setting up roles in the application. See the roles matrix for the case-specific roles in the application.

Add a button in the top right to add case members (see mockups, only visible for case owners and admins).

Owners and admins can add other members. The owner can add Admins, but Admins cannot add other Admins.

After clicking the button, the user selects a person and a role, and then can save them as a member to the case. After saving, the new member should be displayed in the case members table.

The role options will be…

• Case Roles
  • Admin (CRUD, only visible to case owner)
  • Contributor (CRU, D data they created. Can remove items from diagram)
  • Report Editor (R, U report section)
  • View Only (R)

Note that “Owner” is not one of the role options, because the owner is whoever created the case and there will only ever be one owner per case.

Acceptance Criteria

GIVEN I am a (owner, case admin)
WHEN I add a member as a contributor
THEN the member is displayed in the case members table with the contributor role

GIVEN I am a (contributor, report editor, view only)
THEN I do not see the button to add a member

GIVEN I am “case admin”
WHEN I am selecting the role for a new member
THEN I can not select “case admin”

While this template helps define the user story, it is important to remember that the user story is a placeholder for conversation. If you write this up and then immediately push it to your team to work on it, you’re missing the beauty of the user story. Bring your draft of the user story before the team and then have a conversation about it. Invite ideas and questions from others on the team. Define and come to a common understanding of the problem to be solved, or the value to be delivered. Then determine how you will bring forth that solution or value.

If you adopt this template or some variation of it, reach out to let me know!