Writing Ticket Requirements in Jira for the Best Development Results

Writing Ticket Requirements: Why write out thoughtful tickets?

Writing ticket requirements in Jira is a critical part of the development process. It bridges teams together to help create solutions and improvements and keeps all stakeholders on the same page.

Writing tickets should walk you through a story, from the problem to the solution, always with the user in mind. It's just as much of an art as it is a science, and when you learn how to combine all the right elements, you'll find that your Jira tickets will result in more optimal development outcomes.

While anyone on our team can write an issue ticket, they're generally written either by a client or by a Project Manager on our end. The tickets are then worked on (or at least monitored) by several people, so writing out clear and concise tickets is a super important skill. Here are just a few other reasons why.

• Clearly-written ticket requirements minimize the time it takes to fully understand the scope and needs of the issue.
• Offering the right amount of information helps the assignee effectively tackle the issue.
• Communicating the full issue eliminates confusion about the requirements that can be misinterpreted.
• A well-written ticket allows all stakeholders (clients, designers, and project managers) to quickly understand and efficiently review the issue.
• A clear, concise ticket can be used for future reference. If a similar issue arises on other projects, it's easier for managers to find and relay previously implemented solutions and how the team worked through them.

Jira Ticket Writing Best Practices: Our Top Tips for Writing Better Ticket Requirements

Internally, we're always learning new ways to improve our ticket-writing process, and there's a lot to consider. On the one hand, we need to craft a well-written user story, which requires some creativity skills. But, on the other hand, we need to communicate clearly in scope and detail, which requires more strategy and thought. I've chatted with some of our team members and compiled a list of what we find to be the most critical elements of a well-written Jira ticket, so let's take a look at each of these.

Know Who You're Writing a Ticket For

Every department within a company has different needs from a Jira ticket, so it's important to think about this before writing up your requirements.

• What role will each department play?
• What information is most imperative for them to complete their tasks?
• Is there any supporting documentation or examples to share?
• If multiple people are involved, how will each role affect the other?
• What should the workflow look like?
  

Use Issue Templates

Templates allow you to copy fields and content into new issues and replicate them many times. Depending on your needs, you can even copy values into specific fields or create a complex structure of issues, including linked epics with stories and subtasks.

Planet Argon has created Jira ticket templates that can be used for three common Jira issue types: bugs, stories, and tasks, but Planet Argon Project Manager Michael Kurt offers a word of caution in using Templates.

"If a template is too long, people won't interact with all the elements, or they'll give up on using it at all. Templates are good for when you have an urgent bug because they help to remind the person writing the ticket what areas need to be considered and captured, which helps developers find where the issue exists. Overall, with templates, keep it simple, cover critical areas."

Use Precise Language

We've mentioned it a few times already, but clarity is key. If an issue is confusing or there are too many issues wrapped up in one, this would be a good time to either break down the ticket into sub-tasks or break it up into completely separate issues. The idea is that each issue should have a clear problem, a set of requirements, and an agreed-upon solution. Much more than that, a ticket can become confusing, causing delays in getting to a resolution.

"Find the right balance of ticket size. Numerous very small tickets against a single feature or epic incur more Pull Request reviews, which are invaluable but have a cost. Tickets that are too large can generate massive Pull Requests that are too large to review." -Jonathon Turel, Senior Developer

Clearly Define Goals and Scope

Setting clearly stated goals allow the ticket to be worked through correctly. In addition, including the requested change's scope will inform what pages, aspects, features, or changes should be implemented and any other elements within the app or website that might affect it. This part is crucial to planning a proper implementation.

"I've found it really helpful to put the goal or purpose of the ticket (the business need) at the top of the ticket in an Info Panel so that it stands out and is easy to keep in mind for reference." -Michael Kurt, Project Manager, Planet Argon

In defining goals and scope, remember that you don't want to overwhelm the assignee with too much non-essential information. Long text will bury the specific information developers or designers look for, making key details harder to find or understand. There's a fine balance between offering too much information and not offering enough.

"The outcomes should be captured explicitly. Instead of, 'Improve process X,' write 'Improve process X by doing A, B, and C,' where A, B, and C are the exact things that will change to realize that improvement." -Jonathon Turel, Senior Developer

Understand the Why behind the What

Take it a step further, and really get clear on the "why" behind what you're doing. Why does the client want this to be done? Why is this beneficial? Is there a more optimal way to get that result?

"Adding the 'Why' in the ticket writing process can often reveal alternative solutions that may be cheaper or more time efficient, OR result in writing a different ticket altogether that better fits the needs of the client." -Jordan Slo, Senior Developer

Emphasize Acceptance Criteria

When a development team builds a feature, it must meet a certain set of rules to satisfy the user and the customer, in what's called Acceptance Criteria. The goal is to ensure that the team knows what to build before the work ever begins.

"One-line tickets often lead to uncertainty or the possibility for everyone to interpret things differently. It's up to us as engineers to ask those questions, but sometimes there are situations where that one line makes perfect sense, we follow through with our assumptions, and when review time comes around, the ticket creator may have had a different perspective on the ticket. So as much detail as possible is highly appreciated." -William Mena, Developer, Planet Argon

For example, if the Acceptance Criteria is, "Make this button blue," what do developers need to know?

• Where is the button located?
• Should they change all buttons that look like this or just the one on that specific page?
• What specific blue (if we don't have style guides)?

"For acceptance criteria, asking myself, 'If the following statements are all true, would I consider this ticket done?'" -Jordan Slo, Senior Developer

Acknowledge Possible Blockers

This is a super helpful element to add to a ticket because it shows the assignee that you've already worked through possible scenarios that can complicate an issue. Exposing these while writing the ticket will allow them to be accounted for or, even better, solved before development begins.

Use Visuals and Screenshots

Placing images or examples within the ticket instead of attachments makes it easier for team members to see the issue as part of a whole story rather than opening, closing, and scrolling to and from the ticket and downloaded material. This creates more cohesion, better flow, and a clearer understanding of the issue and the solutions.

Include and Introduce Contacts

Another important tip is to provide the names and contact info of other team members who might need to be consulted while working through an issue. This will help prevent blockers and help developers learn which team members have expertise in other areas. Plus, it prevents communication gaps and all the back-and-forth that can keep an issue from progressing.

Update Tickets With Current Status

If tickets are kept updated as to when and if changes have been made, this makes everyone's job easier. Encourage your team to use the ticket management system so that all communication regarding a ticket goes into the same place. For example, if there's an email or Slack thread about an issue, try to keep that communication in open channels, so there's visibility from the whole team. If any requirements or changes are discussed one-on-one or during a meeting, ensure this is added back into the ticket so nothing is lost or forgotten. The best advice is to continuously update tickets with the current status so the whole team knows where everyone else is with their tasks.

Bonus tips

Draft your tickets in a separate document, such as a Google Doc, for easier writing and formatting. This also makes reordering, reworking, and re-editing a ticket much easier. Then, copy and paste the text into Jira when you're ready.

"Sometimes I create tickets for clients during calls with them, so I can confirm the flow of how users get to a page, etc." -Michael Kurt, Project Manager, Planet Argon

If you have an issue with multiple components, here's a helpful recommendation: Break it up into Core Requirements and Development Requirements. This helps give the assignee a clear overview and detailed information and improves workflow efficiency.

• Core Requirements: This is a bullet point list outlining the most critical requirements in the ticket. It should be easily scannable in the working and testing processes.
• Design Requirements: This part of the ticket offers detailed requirements with exact values, sizes, etc. (especially if we don't have a style guide) that will improve design workflow efficiency.

Final Notes

It's a good practice to try to think about an issue from all angles (or as many as you can) so that you can write the most concise, cohesive ticket requirements possible. Investing the time to write your needs out thoroughly improves the team's efficiency, communication, and workflow. It also results in a well-built project that will shine through to the client and the user.