We use Gherkin Syntax for User Stories
Your classic user story looks something like this:
"As a <user>, I want <x> because <y>".
The issue with this approach is that a one-liner isn't as descriptive as we need. Therefore Razroo decided on Gherkin syntax which we like the most. Gherkin syntax looks like this:
- Scenario — a label for the behavior you’re going to describe
- Given — the beginning state of the scenario
- When — a specific action that the user takes
- Then — a testable outcome, usually caused by the action in When
- And — this continues any of the other three operators
Scenario: I want to share my work status with other users
Given we are all a part of the same organization
And admin has signed us all up for the Razroo application
When the user clicks on the "Message Team" button
And clicks on the email input
Then a dropdown of all users within org should appear
Super descriptive, and people know exactly what needs to be done.
Acceptance Criteria
In addition to using Gherkin syntax for user stories, Razroo also writes acceptance criteria to further solidify the task at hand. Here is how Razroo defines acceptance criteria.
Acceptance Criteria: Conditions that a software product must satisfy to be accepted by a customer.
Syntax for Acceptance Criteria
Acceptance criteria is jotted down as a stream of consciousness e.g.
AC:
- Team members receive email when work status is shared.
- Email includes team member's message
- Email includes a link to team member current status page
That's it. Make sure that it's not too granular so that you give flexibility for design, engineers, QA etc. to be creative.
Related Links
Within the realm of engineering this one is usually empty. Nonetheless jotting it down here, as it is important if there is a link to be attached to ticket.
Design Link - We use Miro + Zeplin
Whether it be backend, or frontend software, it is important to attach a screenshot, so there is a way to visual the task at hand.
Jira allows for 3rd part plugins and we use that for both Miro + Zeplin. In rare scenarios, no Miro, or Zeplin will be available. In that scenario, include a screenshot.
Three Guiding Principles
Precise Language
E.g. "Email includes message" <bad> vs "Email includes team member's message" <good>
Checklist Syntax
Make sure the ticket remains as a checklist. The ticket should as efficient as possible and not contain any personal messages. As soon as it deviates from a checklist type syntax, opens the can of worms for the ticket to really be anything.
As Small As Possible
Features are meant to be self-contained, and it's own stand-alone feature. If one of the tickets can be broken into smaller features, then the ticket is too large.