Writing Better User Stories and Bug Tickets
Over the past year at Gecko we’ve added several new members to the team. As a result, one thing in particular became apparent. Our approach to planning was not sustainable. (This is a story for another time.)
An obvious area of concern for us was where the work was spec’d; the JIRA tickets. While product (and sprint) planning is not just about logging tickets, it does form a fundamental part of it. The aim of this post is to outline a structure for how we construct user stories and bug tickets.
To recap our situation. Tickets would be poorly worded and lack suitable descriptions. They often failed to CLEARLY describe a problem or highlight the specific area of focus. This was the major issue. How are you meant to fix something if you can’t replicate it or even understand what the problem is? Adding new members to the team only made the situation worse due them still learning the product and lacking first hand knowledge of previous and existing issues.
I also found there was a bit of a scatter gun approach taken during the writing stage. The support, development and QA teams all had different styles for constructing tickets. (Hint, the development team was the worst).
This meant developers chasing support for better explanations and QA chasing developers for the exact same thing. As a result, disruption and distraction was added to the process and made completing / signing off work frustrating.
For me, the cause was obvious; a lack of structure. It would be easy to blame individuals for not showing discipline but that’s only masking a greater issue. Having no implemented structure (or template) gave people an excuse to write poor tickets.
Not having a template to follow results in random writing styles and makes the whole process a real chore. Anyone should be able to construct and log a ticket, getting this part right lets people do it more efficiently.
While our team practices scrum and agile in principle, we are pretty casual about how we go about it. (Again, a story for another time.) I wanted something not overly formal and could be adapted to the way we work.
After doing some googling, I settled on 2 templates (1 for user stories and 1 for bugs). The aims for implementing these are as follows:
- Help give everyone encountering a ticket a better understanding of the work (or problem).
- Outline a criteria for the work on the ticket and clarify what needs to be done to complete it / sign it off.
- Communicate better where to find a bug and the actions required to replicate it.
- Allow people to work better independently and without disruption by limiting the need for followup information.
- Improve team discipline and efficiency when writing tickets.
(Remember these are templates. They can make your tickets better but thought and time still needs to be put into the writing process. They might look a bit nicer, but without the effort; they’ll still suck!)
User Stories
As a user, I want to hear sound alerts when sending and receiving messages so conversations feel more immediate (and asynchronous).Acceptance Criteria
- It’s done when the outgoing sound alert is played when a message is sent.
- It’s done when the incoming sound alert is played when a message is received.Sound Files
Outgoing sound file: http://www....
Incoming sound file: http://www....
The Summary
Story summaries should be structured as follows:
As [the actor], I want [the something] so I can [the goal].Lets break down the individual parts of the structure further.
- The actor — the person using the feature.
- The something — what the user needs the feature for.
- The goal — why the user needs it.
The goal is probably the most important part of the summary as it makes sure you’re solving the right problem. Struggling to write a goal should make you reconsider if the feature is really that important.
The Acceptance Criteria
This section is a checklist to confirm the work done on a ticket meets the intended purpose and maps the deliverable into smaller outcomes.
For developers this helps break stories into smaller packets of work. For QA it provides a clear checklist for signing off stories with. Each outcome should start with “It’s done when…”.
Other Descriptions
Mockups and images should be linked (if available). These assets really make a difference for everyone involved in the process.
Technical notes should be included if needed. Try to keep this on the factual side though. I’m not a fan of spoon feeding developers but pointing people in the right direction to existing solutions or ideas will help things get done faster. Comment threads tend to be better for more opinion driven content and clearly shows who added it.
Bugs
Users should be able to select (and apply) the ‘disabled’ filter on the ‘Agents’ page without being redirected to another page.Scenario
- Log in and navigate to 'Agents' section.
- Select the ‘disabled’ filter button.Expected result
The agents table should only show ‘disabled’ agents.Actual result
The user is redirected to another page — this is an undefined ‘Agent’ page.
The Summary
The summary should identify what the problem is, the area it occurs and what it’s impacting on. If possible, you should outline the bug from the perspective of the user.
Scenario
This section should be a roadmap for recreating the bug, a step-by-step account of exactly what was done to find it. This means people can find it, fix it and test it efficiently.
Expected Result
An ‘expected’ result is what SHOULD happen after the steps outlined in the scenario are followed.
Actual Result
An ‘actual’ result is what IS happening after the steps outlined in the scenario are followed.
Other Descriptions
For more complex issues, a further summary can be useful. Consider noting previous (or related) issues and any technical aspects.
Remember to include screenshots of the bug in action and any error/console messages where possible. This goes long way to helping everybody understand the issue better.
