Product management is something you learn on the job, not at school or online, but this means there's a lack of educational resources out there. When I was leading the product department at a Berlin startup, I created a guideline on how to write stories on JIRA for the team. I've re-created one to be shared publicly.
First, you need to know what type of ticket to make and the relationship structure.
Epic is a group of related stories and bugs related to a major business goal.
Stories describe a feature or a task and can be comprised of subtasks.
Bugs describe something that doesn't work as expected and how it should be.
Subtasks are usually written by developers to better organise and define their work; cannot be released by itself but only as part of a story or bug.
We're going to focus on a story which is a feature to be developed. The parts of a story will be described from top to bottom.
- If there is an important deadline or message to the developer such as a special procedure for implementation or deployment, I'd include it on top in red.
This is generally the first line of the ticket. It explains in everyday language what the user wants to do and why. It will include who, what's the goal, and what can help accomplish the goal.
Here's the template:
As a <role>, I want to <goal/desire> so that <benefit>.
Here's an example:
As a travelling business man, I want to see an trip duration estimation so that I can make an informed booking decision.
As a cleaner, I want to see customer ratings for each job I perform so that I know if I did a good job or not.
- How important is this ticket? Usually it goes from low to high, but the exact wording is determined by each company.
- Developers who haven't worked on this before would like to know what has been done, what exists, and the general situation. Explain it here.
What needs to be built? Here's an example:
reschedule feature to let the customer change the start time and date of the appointment.
How should it look and behave? Sometimes it could be beneficial to separate those two.
Specify what should be shown where. Here you can also include mockups or prototypes. Attach any graphic assets to the ticket and include hex codes, sizes, etc. Often the graphic designer can help with this. Responsive design should also usually be mentioned here.
Specify how the elements should behave. For complicated features, you should include a flow chart.
Sometimes developers need to have special access or work with other, so include credentials and contacts.
Mention anything that should be tracked.
Add multilingual considerations here.
Although it's not necessarily part of the specifications, it's good to be clear, so I usually explain possible any points of confusion here.
As I'm writing the ticket, I'll have questions so I just list them here until I have a chance to speak to someone who can answer them.
- Often companies would like to keep track of the ROI or business value of a feature so that it can be used during backlog prioritisation and sprint planning meetings. You can talk about revenue gains, cost savings, engagement, customer satisfaction, and other benefits here.
- It's good to indicate which metrics we are measuring in relation to this story. For example, how many users are affected by this and what's the current engagement? This gives an overview of the scale of the feature and a snapshot of the situation before the feature is released.
- Here the developers will estimate the story in terms of man hours or story points.
- Stakeholder: a person outside of product and development who has an interest in this ticket.
- Reporter: the person who initially created the ticket, likely to be you; the product manager.
- Assignee: the person working on the ticket, usually a developer or a QA specialist.
Use cases or Test cases
You can write each use case in this section. Usually it's quite easy if you just go through the flow chart and enumerate them.
Reschedules a cleaning with a perferred cleaner, more than 24 hour in advance
Reschedules a cleaning without a perferred cleaner, more than 24 hour in advance
Reschedules a cleaning within 24 hours of appointment
Test cases are similar to use cases but more detailed and used by QA to test the feature. It's written in a a special format that uses the 3 keywords:
Given - Given lines describe what pre-condition should exist.
When - When lines describe the actions you take.
Then - Then lines describe the result
Example (from TutsPlus):
Given I am on the home page
And I am signed in
Then I should see "Welcome Back!"
And I should see "Settings"
- Here, you'd list anything that you require before the ticket can be approved by QA. Unlike requirements, these are measurable tests and checks that need to be passed to prove it's been correctly built.
That's it. If it's helpful, I'll write more articles like this.