There are many skills that make someone a rock star product manager – sheer intellectual horsepower to grasp and dissect any problem, being able to balance the fine line between religiously listening to customers and refining their voices into what they need, the list goes on. 

However, I would argue that one skill that will make you a gem in the eyes of your engineers is your ability to write clear, concise tickets. I even considered changing the title of this article from “How to write a Ticket” to “How to be Loved by Engineers”, but I will let you be the judge of that. 

I will concede that there isn’t the best or one way to write a ticket. The beauty of modern day software agile teams is that we have moved away from a traditional way of writing lengthy documents that inevitably require a decent investment of time to get it correctly. Every hyper functioning team will gradually their own rhythm and short hands to get stuff done most effectively. Treat the template below as a mere starting point. Remove sections that seem irrelevant to you and add those that benefit you.

For the purpose of this article, I will go over three types of tickets

1. Epic
2. User Story
3. Bug 

For each ticket type, I will enumerate the attributes I would like to see in a ticket and their definitions. Now, popular tools like Jira and Asana can be easily configured to add these are custom fields. However, as a starting point, I would suggest that you just use one free form text field and beautify as you see fit to make the perfect Jira ticket template. 

Epic

Definition

An epic is a large body of work that can be broken down into a number of smaller stories. Epics are almost always delivered over a set of sprints and may require work from multiple teams. 

Content

Project

Most likely, your company will be composed of multiple teams or at least have multiple projects to organize the internal sausage making process. You may be the product manager responsible for multiple projects, but start with assigning a ticket to the appropriate project or team. 

Title

I treat this as a one liner depicting the issue you are trying to solve or how you will solve. For example, if I am building an app that allows user to call for a taxi in near real-time (Uber DUH!), I would implement a feature to allow drivers to go on breaks and automatically reject requests without getting penalized. My title would be something along the lines of “Support for driver break mode”. 

Now you may be thinking why I am emphasizing so much on a title, but I can guarantee that there will come a time when you will have to find this pesky ticket to troubleshoot a bug or untangle some spaghetti code that may have been entangled. Now a good way to test if you have a good title is conducting a quick premortem. Does the title contain words that you would naturally use in your daily life? If so, you are more likely to spend less time searching for this ticket in the future!

Background

One of your superpowers as a product manager is your ability to empathize with the customers and deeply understand your customer’s pain points. After all, we want to find neat solutions to problems rather than finding a cool solution and wrapping a problem afterwards. Write a paragraph or two describing the customer’s use case. Try to write the background in a natural tone of language. What problem are you trying to solve? How are they currently solving the problem? What is the opportunity? 

Benefits

For benefits, I would like to document 3 – 5 quantitative goals that can be achieved with the epic. You want to have the success criteria defined before you start implementing features. For the benefits, I would encourage writers to stick with metrics they can readily measure. Yes, there is value and power in accurate data, but you also don’t want to spend the first half of your epic implementing instrumentations.  

Value Category

Sometimes product managers need to justify what they are doing. This can be to engineers on your team to hype them up or higher beings within your organization or yourself. Personally, convincing yourself that you are doing a good job can be the most challenging part of the job. This can be especially hard if you are in the day to day grind and rarely have time to come up for air. Well, the good thing is that when you are writing epics, you should naturally have some gap so that you can think about what value you are providing to your customers. For this reason, I would like to introduce you to a system I have been using in my professional life. For each epic, I like to assign one of the following values

• Fix: These are epics you have to do in order to retain customers or to get your application in working order. Hopefully you rarely see this at the epic level. I would encourage you to allocate lower than 15% of quarter/half/year on this category.
• Compete: These are epics you take on because you want to compete with other products. Even if your project is unique enough where there are no competitors, these are items you need to do to prevent yourself from being dethroned.
• Differentiate: Now, these are the real fun ones. Not all of these need to be 10x growth game changers. Rather, honestly ask yourself if your epic truly changes the way people look at the use case. 

User Story

Definition

A story is a natural language description of one or more features written from the perspective of the user (e.g., user of your application, API)

Content

Project

This is identical to the project used in the epic. Most likely, your user story will neatly belong to the same project as the epic. 

Title

I treat this as a one liner depicting the issue you are trying to solve or how you will solve at a slightly more granular level than the epic. Remember our epic, “Support for driver break mode”? Well, a user story to achieve that epic may be a feature to allow drivers to specify how long they will be going on the break so that we can predict when there will be a surge of drivers. For that, I may entitle a user story “UI to specify the duration of driver break” or something like that. 

Background

Even in the ticket level, I typically give out some background as to why this feature is a key part of the epic by describing what we are solving. 

Scope

Veteran product managers might shudder at hearing the term “requirements”, but I believe this is really where the requirements go. If you have ever seen the movie Office Space, the product manager has a hard time selling what he does to HR consultants tasked to trim down the company. He frantically explains that he gets the requirements from customers to give them to the developers. When asked why customers cannot go directly to the engineers, he yells out that he has people skills! Well, comedy and memes aside, beyond unearthing needs from wants, it’s also our job to logically document them in a ticket so that developers can implement them. 

Now, every product manager may have an opinion on how detailed you should be, so I won’t necessarily prescribe a panacea. Instead, I will encourage you that spending a bit more time thinking and documenting your thoughts BEFORE development may be a worthy endeavor. After all, this could be one of the best ways to prevent headaches down the road whether the miscommunication manifests in bugs or embarrassing features out to clients. 

Example & Edge Cases

I would argue that examples are a great way to describe product behaviors. Try to enumerate the desired behaviors under various conditions. This would also be a great place to document some of the edge cases to inform developers on where the feature boundaries are. For example, by providing an upper bound for the number of drivers that may go on breaks at the same time for dinner, your engineers can build a better performant system.

User Experience

This may not be relevant in every user story, but as the old adage goes “a picture is worth a thousand words”. You may work on backend tickets that have absolutely no user experience involvement, but for those that do, I would highly recommend that you use a visual medium to depict your stories. Even in instances where you don’t have a dedicated UX designer, you can use quick wireframing tools like Balsamiq to straw man something quick and dirty. 

Shirt Size

One of the tenets of agile is backlog grooming. There is a separate article detailing all the benefits of having discipline to grooming regularly, and I encourage you to check that out! To support this, I like to have a t-shirt size at the minimum. Now, you can go about splitting this shirt size to development vs testing, having multiple shirt sizes like extra small and extra large, but I would recommend Small, Medium, and Large to begin with. If you are feeling completely lost, try the following:

• Small: Takes less than a day to complete 
• Medium: Takes 2-3 days to complete
• Large: Takes about a week to complete

For any tickets that takes more than a week to complete, I would suggest splitting it up into smaller tickets. 

Bug

Definition

A bug is an error, flaw, or fault in the Madaket system (e.g., UI, API) resulting in undesired product behaviors and/or customer frustration.

Content

Project

Most likely, a bug will be related to a user story and should belong to the same project as the user story. 

Title

Similar to the epic and the user story, I would succinctly describe the undesired behaviors occurring. 

Steps to Reproduce

This is the meat of the bug. You should document the steps to reproduce along with the expected behavior and actual behavior to communicate what needs to be fixed. This may sound pretty straightforward in your head, but remember that product managers tend to have A LOT more contextual knowledge than others. Write this as if you are trying to describe the bug to another product manager who may not be familiar with your product. 

Business Impact

You will always have a bug that perpetually resides in your backlog or you will close without resolving. That’s the nature of software development. To make your decision making process easier and communicate your decisions, I like to document the business impact (e.g., number of customers affected due to the bug, impact in revenue) along with any workaround that may exist out there.