Better User Stories From Cooking Recipes

Photo by Brooke Lark on Unsplash

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!

Additional Articles and How to Follow Me

Picture of Nicholas Keene
Picture of Nicholas Keene

I am active on a number of social media sites and writing platforms. This quick article will highlight a few of the additional articles I have written for other platforms and how to follow me on social media. That way you can stay current on what I’m working on and testing discussions.

Additional Articles

Over the past year, I have written a few articles on LinkedIn revolving testing and balance. I recommend taking a look at them if you like what I have written here. Below are links to articles I have written for LinkedIn,, and Testlio’s company blog.

Continue reading “Additional Articles and How to Follow Me”

Four Tips You Need to Know for Better Test Automation

Code on screen
Photo by Sai Kiran Anagani on Unsplash


I had hit a wall, my test automation was taking over 5 hours to run and I wasn’t sure what I could do to bring that time down. I knew that there were environmental issues that were slowing down my tests. Around two hours in the number of page timeouts jumps up to nearly 50%. WebDriver has never worked well with test environments that were extremely under powered, but there was more to it than that. This was a sudden jump in time of execution and timeouts.

Eventually we found the problem, but after all the research, I wanted to loose my head.

Continue reading “Four Tips You Need to Know for Better Test Automation”

I Was Knocked Out This Is What I Did Next

Boxing gloves

I was knocked out! I was asked a question about API testing and I was mentally knocked out. While I have tested APIs before, I have been focused on front-end testing lately. The last time I did it in an automated fashion was as a proof of concept. At that moment, I realized I have been focusing on front-end test automation too much and I really needed to brush up on my back-end testing skills.

Continue reading “I Was Knocked Out This Is What I Did Next”

Seeing the Test Case Through the Forest

"Tree shadows on moss" by Sven Schlager on Unsplash

It is easy to let your regression suite get out of hand. We tend to throw every test case we create in the regression suite. It is a test case dump yard for everything test we create that isn’t in the smoke test. We want to make sure everything works as expected before each release. When we do this long enough, we end up with thousands of test cases.

Before you know it, your regression suite is a forest, when you only need a few trees. There has to be a better way.

Continue reading “Seeing the Test Case Through the Forest”

The Key to Lasting Testing Success are in the Test Cases

Test Cases are the Key to testing success.

Test cases are the keystone of the QA house. Test cases document functionality of the applications we test, training material for new team members, and the building blocks of our test plans. With them we can demonstrate and clarify what we are testing during our regression and production test runs. Without them the following problems arise:  

Continue reading “The Key to Lasting Testing Success are in the Test Cases”