A day in the life of a product person is non-stop communication. Making communication arguably the most critical skill for a product managers and product owners. But communication takes many forms, ones that you may not consider. I believe any transfer of information between two people can be deemed “communication”. The one I want to talk about here is critical to product roles, and defines how specifications are given to engineers. I’m of course talking about jira tickets.

Jira tickets are the crux of a product owners job. Making good clear jira tickets can save a lot of confusion, and when done right, allows your team to steam ahead without your presence, whilst not beating them over the head with a wall of text.

Over the course of my career i’ve worked with many engineers. But one in particular pushed me to always do better with my communication, specifically my Jira tickets.

Together we defined a format that I could easily follow while making cards. The format was designed to be as light as possible, with one main objective. Slash questions between product & engineering by creating a task that are lite, yet rich with information.

Cards can be made for 4 main roles types; data scientists, designers, frontend engineers and backend engineers. The four distincly differing roles deserve their own format, but in order to keep this blog post short i’ll just focus on engineers. For engineers there would be 3 possible format; backend, frontend or bug.

But first, I want to cover 3 principles that apply to all 3 formats.

1. Call things by their name

Like the title states, write the full name of the thing you’re explaining, without shortcuts. The amount of time acronyms saved is probably less than the time wasted trying to understand them. The obvious ones are of course ok, often their name is the acronym nowadays, what does JSON stand for anyway? I’m talking specifically about the ones you make up with your team. For example, we called our payments paid with via payment requests feature “PRs”, which could be interpreted as “pull requests”. Best to just exhaust that extra finger energy writing “payment requests”.

Furthermore, instead of saying “the [thing]”, give the actual name. Instead of saying “the page”, say the path of the page. For example saying, “Releod the /my/accounts/payment-methods page” is more clear than saying “reload the page”.

2. Link generously

It’s easy to blab on, because well everything within the product, or even the business for that matter, is related. But whether it’s relevant is a whole other story. Use links to other cards, epics, docs, reports and so on instead of leaving this information in the task. It’s more efficient anyway to rely on previously created artifacts like documents, charters and so on.

This creates an information landscape that is made up of many small, titled, relevant chunks of information. Instead of a large text dump that can only be absorbed linearly and hard to navigate.

3. Keep tasks small

Big open ended cards leave a lot of room for unknowns. This means a card could be in the work-in-progress lane a long time, yet only the engineer knows where the progress truly lies. This means anyone who wants to know the status needs to wait for a daily scrum, or ask the engineer directly. If the item was split across many smaller cards, then anyone interested could just check the sprint board to understand the status. Some other added benefits to smaller pull requests are that code reviews are less of a time commitment. Other engineers are therefore more likely to review them, boosting throughput.

Now let’s look at some example cards, while I rattle off a few good habits for each section.

User story

• It should never be longer than 1 sentence
• Always name the customer, don’t just say “user”, it’s meaningless
• Remeber to add the benefit at the end, it’s probably going to be something along the lines of faster, easier or cheaper

Current state (optional)

• Where applicable, explain how the feature currently works from the users perspective
• Include screenshot

Ideal state

• Where applicable, explain how it should behave from the users perspective

One day (optional)

• Explain what could be done in future iterations here. In some cases this could be designed to be easily enhanced in future sprints, therefore changing the technical design from the beginning.

Definition of done

• Call everything by its name. Spell out the page path & specific component or module
• Where applicable, give the request API full path and then link to the backend card or the API docs
• Give scenarios and link directly to the respective pages of the design for both happy and unhappy paths.
• Add any translation keys
• Add non-functional requirements, such as SEO or reporting requirements

Stakeholders

• Include the names of the stakeholders and how they should be made aware of the change.

Rollout

• Include information on where the feature will be first deployed, most likely some staging environment
• Where application, give names of the feature flags that will be used to release the feature

The service

• Name the service the change will happen in

Explain the sequence

1. Something triggered the backend to respond, name the webhook, request, event or function call
2. Explain the process undertaken, such as data saved to databased, processed, retrieved or validated
3. Explain the outcome after the processing is done, both happy and unhappy paths

Stakeholders

• Include the names of the stakeholders and how they should be made aware of the change.

Name the source of the problem

• State the page path, component or module where the problem can be noticed

Steps to reproduce

• In order, explain the steps taken to reproduce the bug, including any setup steps

Expected outcome

• What did you expect?

Actual outcome

• What was the actual outcome?