We previously wrote about how to write a great commit message, but before that commit message is ever written, there was (hopefully) a great ticket that was the impetus for the change. Whether or not a ticket is great is subjective, and it is often how well thought out the details are that makes the difference. The ticket might have everything a developer needs to complete the task, but not provide any insight into how to test the final product. Conversely, it might provide all the details the QA team needs to verify, but not provide any insight into the technical requirements for implementation.
Before we examine the specific things that make up a great ticket let’s first examine some of the best practices that further enhance communication and efficiency:
-
Having all stakeholders using the ticket management system and not allowing any communication of requirements via email or other communication tools that silo information.
-
Ensuring that requirements which are discussed one-on-one or during a meeting are added back into the ticket so nothing is lost or forgotten.
-
Having any message conversations in open channels that allow visibility into the decisions for others working on related issues.
-
Continuously keeping tickets updated with the current status so the whole team is aware of where everyone else is with their tasks.
-
Ensure everyone is familiar with the internal jargon and acronyms used, or ensure they are provided with the tools to decipher the terms.
With some ground rules established, let’s investigate the factors that make for a great ticket.
A User Story
A user story provides a high-level description of functionality from a user’s perspective, such as, "when a user logs in they should be able to see a list of past purchases." Great tickets often start with a user story that answers what is needed and why at a high level.
Clearly Defined Goals & Scope
Clearly stated goals from the business allows the ticket to be resourced correctly. Also, a full understanding of the requested change’s scope will inform what brands, sites, regions, pages, etc. a new feature or change will affect, and is crucial to planning a proper implementation.
Accurate Estimates
A well thought through estimation of the level of effort from developers and other stakeholders will make sprint planning/resourcing much more accurate and sprint reviews/evaluations more insightful.
Understanding of Priority
A clear understanding of the business priorities will ensure timely completion and allow the team to plan ahead, avoiding late nights and weekends.
Knowledge of Blockers
Exposing any potential barriers or blockers during the estimating of the ticket will allow them to be accounted for and even potentially solved before development starts.
Screenshots
Providing screenshots and adding arrows and text for clear communication that makes it very apparent what "this" and “that” are, thus avoiding pronoun trouble.
Documented Designs
Providing detailed requirements with exact values, sizes, states, etc. with considerations for edge cases will make any developer forever grateful. Style guides with documented font names, sizes, weights, etc. are another tool that will improve design workflow efficiency. Additionally, designs can provide:
-
Where every piece of information comes from.
-
How items should appear if a given field or other information source is empty.
-
How long or short variants of a given data point are handled and what logic controls programmatic truncation if applicable.
Contact Information
Providing the names and contact information for other team members who may hold key pieces of information that didn’t make it onto the ticket will prevent blockers and help new developers learn which team members have expertise in other areas. Additionally, providing contact information for external parties when working on third-party integrations will prevent communication gaps and middlemen. Sending a quick introduction when rolling a new person into the mix will get you bonus points.
Code Context
Taking the first step is the hardest part, but often a lead developer will know right where and how to proceed. Providing other developers with the names of functions or files to look for from someone with deeper knowledge of the codebase can save an immense amount of time up front and avoids potential refactoring down the road. It also reduces guesswork and more importantly, might reinforce a best practice when there are multiple approaches that would technically work. Examples of previous implementations or before-and-after code samples are also great things to consider providing.
Reliable Information
Up-to-date acceptance criteria that is verified as accurate and updated if/when requirements changed, and the ability for a developer to have 100% confidence in this information makes everyone’s life better.
Complete Logical Requirements
Thinking through default values or fallback values/logic if a given piece of data is empty by default, instead of treating it as an edge case, allows for cleaner code and reduces emergencies and "bugs" down the road.
Component Driven Separation
Giving everyone on the team discrete chunks of work that can be documented, developed, tested, and completed will allow everyone to feel much better about the progress of the project. Providing clearly defined subtasks that allow chunks of the work to be checked off and delineated clearly when working on larger tickets will help with this. Another key to success is having properly managed dependencies for blocking work so effort is not wasted until all blockers are resolved.
This can be accomplished by separating tickets by components, not pages. For example, "social share bar" and "comment widget" tickets that probably appear on every content type rather than a "article page" ticket that includes building and styling all of those components before it can be considered complete.
Exact URLs
When possible, always provide the exact URLs of pages where the offending bug can be found or the new functionality should be placed. This keeps anyone from making assumptions and when properly paired with a nice screenshot, it really takes the guesswork out of recreating bugs or finding where new features should live.
Reproducible Steps
In addition to exact URLs, a thorough lists of steps to reproduce the bug, the expected result, and the actual result will all help a developer quickly pinpoint and understand a problem. It is just as important for developers to provide QA and business stakeholders with steps to test functionality that is not intuitive or simple to test.
Assumptions & Changes
Finally, not all developers are the same. If you ask two developers to solve the same problem, you might get very different solutions, but the more details you provide them, the better the chance of a successful outcome. Additionally, a developer with a wealth of institutional knowledge might need significantly less information to have a clear picture of what needs to be done, while a new hire, internal transfer or external contractor will likely need more information.
However, I would argue that regardless of the expected assignee’s knowledge, the extra time spent to write a good ticket is rarely wasted. Tickets often get passed around as people take vacations, flat tires happen, and children get sick. When these things inevitably occur, we don’t want to rely upon assumptions, which, no matter how good, only need to be wrong once to cause potentially large amounts of wasted time, embarrassment, liability, etc.
Ways to Work This Into Your Project
-
Create a blocked status for your Agile or Kanban boards and utilize it liberally to ensure high visibility into the unknowns and show others how much time is lost due to blockers.
-
Loop project managers into conversations with the person who filed the initial ticket so they see first hand the level of effort required to track down answers.
-
Talk through the issues during sprint review and review what did and did not go well.
-
Allow developers to review and estimate issues before they are included in a sprint and require clear requirements before accepting a ticket.
-
Don’t just complain; be a part of the solution. Educate stakeholders on the structure you want to see for requirements and provide them with tools to help communicate more clearly such as logic maps, data flow diagramming tools, etc.
What Now?
I encourage you to think of a good ticket not just as a means to an end; be that a fixed bug, a new feature, or new design. Instead, treat it as an opportunity to show respect to each of the many professionals that will touch the ticket through its lifecycle by providing them the information and tools they need to perform their job to the best of their abilities. This respect goes in all directions, from ensuring good requirements for developers, to writing good testing instructions for QA, writing quality code for a great product and providing stable hosting infrastructure. This all culminates in a well-built project that shows respect to what this is ultimately all about: the user.
