Example User Stories
How do I write a good User Story and is there a specific format to follow?
Last updated on January 31st, 2024
User Stories are the backbone of any Agile development project. Ensuring they are clear and concise is not easy, but over time you will find your style and drafting them will become second nature.
User Stories should always identify the person (or persona) who will benefit, what they need to achieve and why they need to achieve this. Exactly how you write this is up to you and your development team, but the standard way is:
As a [persona], I [want to], [so that].
You must also need to include one or more Acceptance Criteria (A/C’s). A/C’s are descriptions of how the thing you are developing should function. They can be written in a Given, When, Then format but, they do not need to and sometimes a bulleted list will be perfectly acceptable.
And, finally before a User Story can be developed it must meet the Definition of Ready (DoR). The DoR is a team-specific document which defines what is needed in the User Story that it can be considered ‘ready’.
Here are some example User Stories I’ve crafted with product development teams:
Example User Story – Viewing a profile
This User Story described what a logged in user would see depending on the completed state of their pets profile (i.e., The pets they had and the the number of medication reminders per pet).
Description
As an authenticated user with one or more pet profiles vising the dashboard page I want to see my Pet Profile Card(s) showing me my pets name and their current medication reminders, so that I can clearly understand what has been set-up.
Acceptance Criteria #1
- Given I am an authenticated user on the dashboard page with one or more pet profiles
- When I look at a Pet profile card that HAS associated reminders
- Then I will see the following fields:
- Pet icon
- Pet name
- Product reminder
- Dose day [label]
- Product reminder dose day(s) (mm/dd/yyyy) – a maximum of 3 reminder dates will be shown, based on the date they were last created/edited. If a specific pet has more than three medication reminders set-up, then the the 4th or more oldest one’s will not be displayed.
- View full pet profile button [Primary Button]
Acceptance Criteria #2
- Given I am an authenticated user on the dashboard page with one or more pet profiles.
- When I look at a Pet profile card that has NO associated reminders
- Then I will see the following fields:
- Pet icon
- Pet name
- Message to set up a reminder
- Add a reminder button [Ghost button]
- View full pet profile button
Acceptance Criteria #3
- Given I am looking at the Pet Profile Card
- When I click on the view ‘full pet profile button’
- Then I will be taken to the full pet profile for that pet
Acceptance Criteria #4
- Given I am looking at the Pet Profile Card for a Pet WITHOUT reminders
- When I click on the add a reminder button
- Then the add create reminder modal overlay will be opened.
Example User Story – Product Filter Functionality
This user story describes the filter functionality used on an eCommerce website. As the filter functionality is significantly different on desktop and mobile devices I created two distinct User Stories for it. I would normally try to avoid doing this but as they are so distinct then it is a better option in this scenario, as it keeps the Acceptance Criteria to a manageable length.
I included three distinct acceptance criteria when writing this; 1 for each of the filter states, and as they were interactions that could potential have an automated test written for them I used Given, When, Then for the format.
Description
As a website shopper, I want to be able to filter the products displayed on the product category page, so that it is easier for me to find a specific product that I want to purchase.
Acceptance Criteria 1
- Given that I am a website shopper viewing the product category page on a desktop device.
- When I select an option in the filter (e.g. Clothing Item > Shirts) on the left hand-side of the screen.
- Then the product category page updates and I am only shown the products that match that category (e.g. Shirts).
Acceptance Criteria 2
- Given that I am a website shopper on the product category page and I have already filtered my results with one option (e.g, Shirts).
- When I select an additional option, to narrow my search (e.g. Colour >> Green).
- Then the product category page will be updated and I will I am only shown products that match both options (Shirts that are green).
Acceptance Criteria 3
- Given that I am a website shopper on the product category page and I have already filtered my results with two options (e.g. Shirts + Green).
- When I remove one of these selections, to open-up my search.
- Then the product category page will be updated and I will I be shown all shirts (not just green one’s.)
Example User Story – Google Map Marker
This User Story was to add a additional field to a pre-existing map marker on Google Map.
Description
As a Website User using the contacts map, I want to be able to understand when the distributor in my home country is located in another country so that I am not confused when I see a foreign address in the information.
Acceptance Criteria #1
- Given that I am on the sites and distributors map
- When I click on the info window for Spain
- Then I see a field under the main address telling me ‘the distributor for Spain is based in Italy’
Acceptance Criteria #2
- Given that I am on the sites and distributors table
- When I filter on ‘Spain’ in the country dropdown
- Then I see a text field under the main address telling me ‘the distributor for Spain is based in Italy’
Example User Story – Criteria Search
Description
As a broker I want to be able to keyword search and sort residential and BTL criteria to find key information more quickly.
A/C 1
When I view a criteria keyword search then I will see:
Desktop
- Search box (with placeholder text)
- ‘Search’ button (with icon and text ‘i.e. ‘Search’)
Mobile
• Search box (with placeholder text) ○ ‘Search’ button (with icon) *On mobile the text e.g. Search will be hidden.