User Stories & Acceptance Criteria
This documentation is a work in progress, and we are looking to improve the Development Cycle. It describes why we use User Stories & Acceptance Criteria, and how to write them.
The Why#
A common challenge in software development is the fact that we tend to write product requirements/tickets in many different ways, and based on our own (voluntary or involuntary) biases, which can lead to misunderstandings regarding a topic between stakeholders (PM, Design, Dev, QA). To mitigate some of these challenges, we’ll work with User Stories & Acceptance Criteria. This should help us by bringing clarity and structure, have well defined conditions of satisfaction, and a shared understanding of the things to be done.
Definitions#
User Story#
User stories are short, simple descriptions of a feature told from the perspective of the person who desires the new capability, usually a user or customer of the system. Every feature should have at least one User Story scenario. The QA should review all User Stories of a feature to make sure that they make sense, and we will focus on solving the problem.
A user story follows this template:
As a type of user (who), I want to action/functionality (the what) so that benefit/acceptance criteria (the why).#
To get a better understanding, here are a few examples of User Stories for a Dog Walker App:
Rule-oriented Acceptance Criteria#
Acceptance Criteria are the conditions that a software/product must meet to be accepted by a user, a customer, stakeholder or other systems. A user story on its own leaves a lot of room for interpretation. Acceptance criteria clarifies the expected outcome(s) of a user story in a concrete manner. It also gives developers and QA a clear-cut way to determine whether a story is “done.”
Gherkin Scenario#
Every feature should have enough Gherkin Scenarios that should preferably be created by who created the issue and reviewed by the QA. These scenarios would help the person test the feature, giving a north to what should validate into the feature.
Things we should keep in mind, related to User Stories & Acceptance Criteria:#
- Not everything is a User Story, and we should avoid transforming everything in a User Story. Meaning that we still have bug tickets, technical maintenance tasks, etc.
- User Stories are not measurable, as they act more as hypotheses. But tasks under user stories, for sure can/should have estimates.
- User stories should be Sprintable, meaning that they should meet the basic criteria before they are added in a Sprint: they have the right amount of information (not too much/little details), can be completed within a sprint, has a clear and precise way to verify whether or not the User Story has been completed.
- This is a team effort. Even if usually User Stories & Acceptance Criteria are created by the PM/Team Lead, involvement of each team member will help clarify & streamline the process. For example a PM can have a high level picture of the User Story, and a Developer/QA can add more technical/specific Acceptance Criteria.
Examples#
An example for Templates Cloud.
User story:#
As a Neve user, I want to use a search field to search for a keyword, so that I could find relevant sites.
Rule-oriented Acceptance Criteria#
- The search field is placed on the top of the view
- Search starts once the user types the first char
- Once the user types the first char, the Clear input icon will appear on the right side, inside the Search Field
- The field contains a placeholder with a grey-colored text: “Search for a starter site...”
- The placeholder disappears once the user starts typing
- The user can’t type more than 200 symbols
- If there are no result found, the view will change to “No results found. You can try a different search or use one of the categories below“ (tiles with Sites Categories will be displayed below).
A fictional example with Neve Customizer
User story:#
As a Neve user, I want to bind the Headline sizes on all Devices , so that don't have to change it manually for each device.
Rule-oriented Acceptance Criteria#
- When the Size binding is enabled, any modified value will be applied on all devices
- Once the user disables the binding, the values are not linked and equal to the last value
- When hovering on the Icon, it should say "Link values"
- The icon has 2 states, that are working accordingly (Enabled/Disabled state)