A well written recipe is an amazing gateway to trying a new dish for you and your family. It’s also a golden opportunity to learn something new! The same is true for a well constructed user stories or any other type of ticket in Jira. Today, I’m going to introduce you to my recipe for success in ticket writing and why you should demand better recipes, I mean tickets before you start your sprint.
Now, if your job is related to software development (e.g., developer, tester, product) and you don’t normally cook, you might not understand where I’m coming from here. But, I’m sure you will appreciate it in a few minutes.
A taste for the past
Humans have been cooking their food for longer than recorded history. Along the way, we discovered that mixing different items together made the food taste better. You would think that if the first written document was an ancient spread sheet, then the second document would be a recipe, right? Sadly, it wasn’t. In fact for much of human history, when a recipe was written down, it was a list of ingredients with a vague set of instructions. This lack of specificity allowed for an open interpretation of what was mixed together and what the end result should be. An open interpretation of what the end result should be? I feel like I’ve seen this at work.
It really wasn’t until the last few hundred years or so that recipes began to standardize around a format of listing ingredients (with measurements) and instructions for preparation, cooking, and serving. This change allowed anyone with a copy of the recipe to consistently repeat the process or improve it.
What does this have to do with Jira tickets?
A well defined ticket allows everyone to understand clearly what needs to be done, just like a recipe. The role of the Product team is not an easy one and I give them credit for even wanting the job, but ticket writing is the most difficult. You must put down in words what the end result must be with guidelines on how it should perform or interact.
This sounds and looks like ingredients, steps to prepare, and serve. Also known as a story, requirements, and acceptance criteria.
If you look at most cooking blogs today, 99% of them start with ‘a story’ about the recipe. The difference for software is that we want to explain the “why we are doing this” in a user story, so that we understand what we need to do. The requirements are baked into the how and why we’re doing this, and the acceptance criteria tells us when it’s done.
Recipe for Success
One key difference between a recipe and a user story is the format order. In a recipe you start with listing the ingredients and the measurements you need, followed by your preparations for the ingredients and then how you mix / cook them. Finally, a recipe tells you how to serve the dish. A user story starts with the user and what they need to be able to do. Followed by the requirements and finishing with the acceptance criteria.
Bad recipes look like my post about savory oatmeal, the same is true for bad tickets. A bad ticket can have a title like this, “Add new function for Invoice”, and then have no body to it. It’s just the title. And yes, I have seen tickets like this at every place I’ve worked at. I’m sure you have too!
So how do we make the user story better?
Using our example from above, “Add new function for Invoice”. That’s not really something that can be done, because invoices are standardized, the request is probably for a new feature around the invoice like viewing in a PDF. Changing the title is a great way to improve this, “Add view in PDF to invoice screen”, helps clarify the ticket. Now we’re done, right? No, we’re not. We don’t know the “why are we doing this” part of the ticket.
We need to know who the user is and what it is they want to do with it. Obviously, the user is someone in account or finance, right? So, they just want to open the PDF in Adobe, or their browser, or to download it, right? Well, that assumption that it is for someone in accounting or finance could be wrong. The end user could be a customer outside of the company. Also, there is the assumption of how they want to use it with implied purpose that got slammed in there. These details matter, because that is how you know what you need to do. Like a recipe that tells you to preheat the oven to 400 degrees and cook for 50 to 60 minutes, the details layout what the actions are and for whom. So, let’s add story to the user story.
The accounting team needs to export our invoices into PDF, so that they can be emailed to our auditors.
In this example, we learn three important pieces of information. First, the end user is not the accounting team, but the auditors. Second, this feature will not be used every day. Finally, it must always work.
Are you wondering how I jumped to the conclusion that it must always work? That’s an implied acceptance criteria. On the average day, no one needs to interact with an auditor; however, when you do get a request from one, you need to respond quickly. This makes the process for everyone involved easier, but also show your company takes these request seriously. That means, your feature always needs to work.
We have a corrected title and a user story, so we’re ready to go, right?
Not yet.
We’re missing the full acceptance criteria still. We have only the implied one. We also don’t know if this is supposed to be a button on the screen or automatically downloaded. Should we open a modal to handle the emailing from within the system? Since this is for auditors, should we log this request (e.g., who was logged in and triggering the PDF creation, who was it sent to)? These are all important pieces of information.
It’s not easy
As you know by now, it’s not easy to write brilliant user stories. If it were, then everyone would be doing it and this post wouldn’t have been needed. So, it’s everyone’s responsibility on the team to help improve user stories, tasks, and bugs to be great recipes.
The example that I played with above was for a front end user story and I know that’s not always the case. Tickets for the backend are often vague and open to interpretation because there isn’t a visual component, but you should always know who or what the work is being done for. The creation of an API is not an isolated task for no one to use. It will be used for another application either within your company or for a customer. That changes the nature of the ticket a bit, but it improves it greatly because then the developers and testers know who they are creating the ticket for.
User stories should tell a story that anyone on the team can follow. They need to drive the team to a destination that everyone can understand they have reached. This is done by being consistent and providing structure that everyone working on the ticket can understand, much like a recipe.
If you liked this content and would like to see more of it, please like, comment, and share it. Thanks!
