When I got my job at Wayfair in 2020, I was excited to join a lean, scrappy team that maintained a b2b tool that drove huge amounts of business. I was coming from a role where I had worked mostly in a silo, so I was especially excited to be a part of a development team again. I found very quickly, however, that much of the team had so much expertise in the tools we were using that they had this predetermined assumption that other developers had the same background, experience, and knowledge they did. The major issue was that the tools we were working on were internal and proprietary, so many of the newer developers didn’t know them as well as the seasoned devs. Now, this isn’t an issue generally. However, it became very problematic when Jira tickets were created, prioritized, estimated, and assigned with few details. Sure, the title explained the general issue, and the seasoned developer who wrote it probably knew exactly where to start looking to make changes, but those of us who were newer to the platforms had very little to build on to get started. This caused massive holes in efficiency, where we were constantly hounding the more tenured developers for more information.
Another byproduct of this setup was that our tech design meetings tended to drag on as more and more of us had questions about tickets that were being presented for estimation. Details were constantly being eked out in conversation but none were being recorded. These meetings would drag on, and then the same questions would come back up once the ticket was assigned (unless the assignee could magically remember the conversation from weeks ago where the questions had been initially asked).
This workflow was incredibly frustrating and inefficient. But, there’s hope! A short time after we recognized this issue and discussed it, meetings started flowing smoother, taking less time, and being more impactful. Tickets were rich with details and easy to action on, test, and complete. Here’s how we did it.
The Problem: Unprepared Tickets and Lengthy Meetings
Our tech design meetings would often be derailed by tickets that lacked sufficient detail. Developers, designers, and other stakeholders would spend too much time seeking additional information or clarifying vague aspects of a task. This not only lengthened our meetings but also delayed development as assigned tickets would frequently bounce back, requiring more clarification before work could proceed.
A great example of this might be a ticket that was reported by a tenured dev that simply stated “We need to fix pricing for flooring skus.”
Clearly, without a sufficient amount of background information there is absolutely nothing you can do when you receive this ticket. What’s the problem with pricing on floor skus? What is expected to happen? Does quantity of the sku in cart matter? There are a lot of open questions and really no way to begin work without hopping into a meeting. A better ticket description might be.
“Floor skus are bulk-priced and our system is not handling the pricing/quantity math properly when the quantity in-cart exceeds the bulk pricing thresholds.”
Now, there’s still not enough detail here, but at least it explains the problem properly.
I’m not going to tire out the example but the developer(s) would have to flesh out all of these details with repeated questions, conversations, and presentations until we had enough details to estimate or work on the ticket, depending on the current task. This led to a lot of lost time that we, as developers, couldn’t get back.
The Solution: Implementing Ticket Templates
To solve this issue, we developed a set of structured ticket templates tailored to the type of work being done. These templates ensured that every ticket—whether a bug report, design change, feature request, or optimization task—contained all necessary information before being discussed or assigned. The rule was simple: if the template wasn’t fully completed, the ticket was not ready for the meeting or for development.
Bug Reports
Description:
A brief, but detailed description of the problem.
Expected Behavior:
A more detailed explanation, including screenshots or Figma references, of how things should be working.
Actual Behavior:
A detailed description on what is happening and how it differs from the expected behavior.
Steps to Recreate:
Specific, detailed, steps on how to recreate the issue. This needs to approached such that someone could open a new incognito window into the tool and recreate the issue without deviating from the steps.
(optional) Developer Notes:
This is an optional section where we can include suggested approaches if we already have a good idea on where this should go or how it should be developed. We don’t want to force developers to do things a certain way but any guidance here can help speed up the ticket execution later.
(optional but preferred) External Impacts:
This is where we callout any external sources that may impact this work. Are there teams that have already created a workaround for a bug in our API who will need to be notified when we fix it? Does this bug rely on other teams/apis/sources for information that could potentially impact how long it takes to fix this?
(optional) Impact:
Is this having a known, measurable impact on the team or business? This is not always known or easy to measure, which is why it is an optional field. But it is important to know for prioritization if it exists.
Design Changes
Description:
A brief, but detailed description of the problem.
Expected Behavior:
Screenshots or Figma links for the expected, designed behavior.
Actual Behavior:
Screenshots or videos detailing what is actually happening, as well as a description of what is happening and how it differs from the expected behavior.
(optional) Steps to Recreate:
If this is a specific UI element that only shows up in particular situations, we need to know exactly how/when this should be present so that we know how to test our changes.
(optional) Developer Notes:
This is an optional section where we can include suggested approaches if we already have a good idea on where this should go or how it should be developed. We don’t want to force developers to do things a certain way but any guidance here can help speed up the ticket execution later.
(optional) Impact:
Is this having a known, measurable impact on the team or business? This is not always known or easy to measure, which is why it is an optional field. But it is important to know for prioritization if it exists.
Feature Requests
Description:
A complete detailed picture on what the feature is. How it should function, what the expected inputs/outputs are, etc. We should also include any reasoning we have for why this feature is being requested here.
Developer Notes:
The developer should use this section to provide guidance on known frameworks/patterns that should be utilized to fit into the rest of our codebase seamlessly. We don’t want to force the developers to write code any certain way but any guidance here will make the ticket execution faster and should lead to more streamlined PR conversations.
(optional but preferred) Mockups:
If we have example payloads, screenshots, or Figma references that should guide development these should all be included here.
(optional but preferred) External Impacts:
This is where we callout any external sources that may impact this work. Are there teams that have already created a workaround for a missing feature in our API who will need to be notified when we add it? Does this feature rely on other teams/apis/sources for information that could potentially impact how long it takes to build this?
(optional) Impact:
Is this having a known, measurable impact on the team or business? This is not always known or easy to measure, which is why it is an optional field. But it is important to know for prioritization if it exists.
Optimization Tasks
Description:
A brief, but detailed description of the problem.
Current State:
A more detailed explanation of how the code currently works and why it is inefficient.
Preferred State:
A detailed description of what we aim to fix with this optimization, what goals are we trying to accomplish.
Developer Notes:
This is a guide from the developer who is calling out the need for optimizations. This should call out specific files and tests that need to be edited as well as the specific sections that we believe are the bottleneck in performance or causing confusion.
Testing:
Notes on how this optimization can be validated or verified. We not only need to see that we actually did gain something out of this process (and it might be something we can brag about), but we also need to verify that the changes didn’t impact any known external processes that relied on the code changed.
External Impacts:
This is where we callout any external sources that may impact this work. Does this feature rely on other teams/apis/sources for information that could potentially impact how long it takes to build or test this?
Impact:
Is this having a known, measurable impact on the team or business? This is not always known or easy to measure, but in order to justify a refactor or optimization we need to have this information.
The Impact of Templates
The results were immediate.
We saw quickly that we could get through about 3x more tickets in a single hour-long tech design meeting than we could before. Also, the discussions we were having in these meetings were more beneficial and impactful. We were taking the time to call out edge-cases, impacted teams, and potential show-stoppers or bottleknecks in the process, prepping devs for the work instead of spending all of our time trying to grasp for more details. We also forced ourselves into a pattern where we recorded all of this feedback into the ticket either in the description or comments. The templates were a constant reminder that these details were important and that they needed to be present and easy to find. In a way, these templates re-trained our brains into taking a documentation-first approach towards these tickets, ensuring that whoever grabbed the ticket, whether it be a junior developer or seasoned engineer, would have enough information to write some high-quality code.
Next, we noticed that our development cycles were more concise, our estimates were more accurate, and we were hitting that coveted 100% completion mark on sprints far more often than we ever had before. We were able to clear our board almost consistently. Not only is it important for the business because they were receiving updates when we told them they would receive them, but it was a huge confidence booster for the team as you’re constantly putting yourself in a position of success. Our stakeholders saw our improved efficiency and throughput and gained a greater trust in our team and our process. They also noticed that our code was a higher quality, as we were able to spend more time focusing on the actual problem at hand.
We knew from the start that this would make our lives better as developers, but we hadn’t realized how much of a positive impact it would have on our business partners as well.
Key Takeaways for Other Teams
If you feel like your team is constantly burdened by a lack of information it might be worth it to investigate if creating structured ticket-templates might work for you. It’s important to call-out that this does take additional developer time to flesh out the tickets with enough detail to action on. I do believe this is a justified cost and it leads to huge cost-savings in the long run as it improves your workflows tremendously, but it’s important to call out that these changes don’t just happen for free. Someone has to dedicate time to doing research and writing up a high-quality ticket and that someone is likely to be your development team.
That being said, it’s easy to see how huge of a win this can be for a team. To get started I would recommend a few short steps.
First, assess whether or not you really have a problem. Sometimes one or two developers are struggling with documentation or knowledge-transfer but that’s not indicative of a full-scale problem with your tickets. Perhaps other things like better on boarding or documentation might resolve some of those issues.
Second, if you do find that this is a widespread issue that needs resolution, the next step is to categorize what type of tickets you normally get and what type of information is required in each. The obvious candidates are bugs and features, however depending on the nature of your companies business, maybe you have other types of tickets that constantly flow through your system and have different needs. Maybe your team manages an ETL pipeline and you need to know what inputs/outputs are impacted on tickets related to that. Maybe your team owns an SDK and the tickets related to it need to be handled in a special/priority manner and need to include what business functions might be impacted by a change? Know your team and their requirements so you can determine exactly what types of templates are required.
Next, once you have all of this information, put it in writing somewhere shared that everyone has access to. Perhaps this is a shared document, or a wiki page that the team manages and accesses, or perhaps you can even create templates in Jira itself, forcing people to use them. No matter what your approach is, you need to get buy-in from the team and developers which means they need to be able to see it. This is one of the most important steps because this process will go no further unless you have 100% buy-in from anyone who will be writing tickets. Present these templates to your team, collect feedback, explain how you think this new process will impact you and your stakeholders. Make sure everyone on the team is comfortable with the new process.
Last, you have to enforce these changes. Tickets presented without enough details should be tossed back immediately without discussion. It’s important to be strict about following the template guidelines or people will always find reasons to get around it. “This issue is too critical, I don’t have time to write it up” is a common complaint that we would receive. However, being strict with the need for a template and working with people who are trying to get around it, you will eventually win them over.
At Wayfair we saw massive improvements to our team’s process as well as morale by making the small changes listed above. I hope this helps your team, too.