Have you ever presented SEO opportunities to a dev or technical team and been asked to “log a ticket” for a fix or enhancement?
What’s that mean, really?
When debugging SEO issues, you may find yourself needing to translate the details you found to the dev and technical teams in the form of a support ticket, or a request to investigate or resolve a known issue.
The ticket may have to be submitted through a support email address or through a project management tool (Jira is a popular one that I typically use as website migration tool, ongoing SEO support, and internal communication). Where and how you submit it can also depend on the project – e.g. website migration project, technical enhancement, or resolving a known issue.
But how do you create an effective SEO support ticket and where does it get submitted?
Below, I want to share some SEO tips around ensuring the ticket is streamlined and, although the ticketing system might differ across brands, the guidelines I’m going to recommend are tool-agnostic.
Let’s get started.
What is a SEO development ticket? Why does it matters?
First let’s make sure we have a clear understanding of what I mean by a Ticket.
There are many ways to keep track of a project and its activities. One of them is through a ticketing system.
In a ticketing system, tickets are the way to log new tasks to be completed.
Tickets can be created either by the team members or by an external user that has a request that needs to be fulfilled.
This second case is the scenario that we, as SEOs face and is the reason why knowing how to submit a good development ticket is key to implement our SEO suggestions.
6 SEO ticket writing best practices you need to know
1. Explain the issue in a clear, precise way
Opening a broad ticket can be left for interpretation and increases the likelihood that a development resource needs to inquire further for more clarification. This, in turn, requires more conversation and more back and forth needed to understand the issue.
An open-ended request with a very specific outcome is hard to achieve especially if SEO isn’t in your dev resource’s background.
For example, let’s say there is broken Schema on a site and you have to file a ticket for it, stating “Fix broken Schema” as the resolution doesn’t help. Rather, be specific by stating the following:
- What exactly is broken?
- Where can you find the issue?
- What does the issue look like?
- How is it supposed to look / behave?
Don’t forget to include images or video recordings if necessary to make your point clear.
By providing details on the above, you’ll prime your development resources with what to look out for.
2. Explain the expected output in detail
Not all devs are going to be an SEO expert – far from it – and what comes natural to you does not come natural to them, no matter how talented they are.
They’re going to follow the ticket details to the T and won’t think twice about SEO best practices unless the tickets come with specific requirements.
If you go through the SEO ticketing process often enough, the tech teams may build a deeper SEO understanding over time – bless them – in the meantime, be specific.
For example, let’s say your building a custom feature on faceted search – i.e. SEO friendly URLs – but you leave it as “Build SEO friendly filter URLs”. That’s great but what does that mean?
Don’t leave it to your development teams whims to understand; rather focus on questions such as
- What site sections should it impact?
- What behavior should be exhibited or avoided based on what logic?
- What constraints should the logic abide by? (Category depth, filtered selection)
3. Stay relevant
Relevancy is a balance between being specific and staying on topic. Don’t loop in other issues that are not hyper-relevant or merit their own SEO tickets, and don’t talk about a broad subject if it doesn’t contribute to the outcome.
For example, let’s say your content generates after JavaScript is executed, making it harder for search engines to read your content. When you write the ticket, don’t go into the history of JavaScript, when it was founded and by whom. Talk about why JS may not be ideal for SEO, where the rendering issue is found, and how to resolve it.
4. Explain only one issue per ticket
Don’t overwhelm your partner by having too much in a single ticket; it becomes more difficult to manage.
As we have seen so far, all tickets should include:
- A clear explanation of the issue
- The steps to replicate the issue
- A clear explanation about how to fix the issue
- Acceptance criteria for the solution
This can be a lot of information for just one issue. If we multiply that for two or more issues, is easy to see how a ticket can become problematic to manage.
When a ticket has only one issue it is easier to understand it, to track it, to prioritize it, and most importantly, to solve it.
But what if you need to put more information in the ticket?
That’s when my next tip comes in:
5. Link to other relevant tickets
You may be dealing with a number of relevant SEO tickets, either all being managed concurrently or from a past project. When you encounter a past SEO ticket that is relevant to a current SEO issue, link to it. This is especially true if the current SEO issue is born from a previous SEO ticket. It provides context and saves everyone time from having to look for it.
Depending on the PM tool, you might be able to create groups of tickets. For example, Jira allows you to create an “Epic” grouping of tickets, which are tied to a certain theme; perhaps around a development support engagement, migration project, or other project. I recommend creating an SEO project plan and tracking it regularly.
6. Define how a successfully solved ticket looks like
Again, be specific.
Testing criteria and requirements help serve as the basis for a successful ticket.
That is, guide your development teams on how they should be testing the criteria and what they should be required to incorporate into an ideal behavior or state.
This is why it’s crucial not to be vague or leave things to assumptions.
In the eyes of devs the ticket may be complete but that’s only because your ticket may not have specified what the expected behavior should be.
Outlining expected behavior gives all your team members a blueprint of the working final state.
For example, let’s say you suggest to add FAQ Schema to an article.
What is the criteria to mark the ticket as complete? What should the Schema look like and how is it tested?
Some criteria to mark the ticket as complete could be:
- Schema has been added to the <head> of the page inside an <script> element
- Schema is nested inside a “@graph” property.
- FAQPage Schema contains the property “isPartOf”.
- The value of “isPartOf” should contain the @id and name of the article Schema.
- validator.schema.org gives 0 errors and 0 warnings
SEO ticket structure and examples
Organizations will differ on how to construct their support tickets.
That is, they may want a description, a scenario, why a ticket matters, requirements, etc.
Regardless, the info I’ve outlined above should help you fill in a support ticket in whatever manner your organization structures them.
I’m going to use my preferred ticket structure, one which I’ve received positive feedback around.
Example 1: Incorrect SEO ticket structure
We’re going to start with the example “Fix broken schema” and outline why it’s incorrect.
Name:
“Fix broken schema”
Description:
We are being penalized for Schema errors; see audit attached.
Incorrect Ticket Notes
The above ticket lacks an immense amount of detail. What’s more, it urges the dev team to review an audit, rather than breaking down its findings; requiring more effort and time to research.
Example 2: Ideal SEO ticket structure
Now, we’re going to take the same situation, where we’re requesting the team to “Fix broken schema” and expand on it.
Name:
Convert Product Schema on Product Detail Pages to JSON
Story (Description):
Product Schema enhances search results through rich snippets, or enhance search listings. Currently, product schema found on Product Detail Pages (PDPs) is in Microdata (HTML based) but Google recommends using JSON.
How To Replicate (Observations):
- Visit example PDP [insert link]
- Open source code
- Search for “schema”
You will find product schema is found across various elements in the HTML document. These elements will need to be nested within one another.
Expected Behavior (Requirements):
Requirement 1
Product Schema types and properties should be converted to JSON. The below Types, and any associated properties, should be built out in the new JSON markup.
Requirement 2
All JSON Schema should be placed in the <head></head> section of an HTML document.
Acceptance Criteria:
- Schema should be found in JSON, devoid of errors – you can use the Schema Markup Validator
- Schema should be nested under one another
- JSON markup should be found in the <head> section of the HTML document
Other Considerations:
It’s possible Product Schema ratings and reviews may be fed through the ratings and reviews partner. Conversations with the 3rd party around how to support conversion to JSON may be necessary.
Ideal ticket notes
We took the issue and expanded details around various aspects of the ticket; it’s way more robust and less room for error.
Areas where we improved the ticket include:
- We expanded on the issue by speaking to it in the name of the ticket
- We pinpointed the issue in the description
- We inserted links to relevant webpages that may guide the developer
- We elaborated on how one could find the issue and how it should function
- We created requirements that the team can use to define a successful behavior
- We shared other considerations that may inhibit the ticket from progressing
Weigh the ticket’s priority
You may not want to hear this, especially if SEO is your bread and butter.
But…
Despite being an SEO priority, your ticket is just 1 in a sea of tickets across teams – some are mission critical, some are nice-to-have’s, and some just are placeholders.
Keep in mind that you’re up against team budgets, timing, and resources.
- All teams and projects have allocated budgets. You have to be able to ensure that your ticket is funded in some way.
- Depending on the project, you may be working within sprint releases. If so, you only have a window of time to create and execute an SEO ticket until you’d have to wait for a later sprint (read more about agile / sprint releases at The SEO Sprint).
- Your teams might be so swamped with projects, you may not even have the bodies to work on your SEO tickets.
You have to be honest – what value and impact does the SEO ticket have?
- Is something seriously broken, that is, does something require repair?
- Is there a detrimental issue that is compromising site performance?
- Is it costing the brand resources and money?
- Are you adding an enhancement to an experience based on an opportunity?
- What sort of uplift does a new enhancement offer relative to other initiatives?
- Do you need the development team? (e.g. you don’t need a dev team to start a redirect map)
I say this because nothing irks development and project management teams more than having multiple top priorities, with an inability to discern the real level of impact.
Conclusion
Although it sounds like tedious work, filing SEO tickets is not for the faint of heart. You have to be intentional about the details you relay and your level of communication.
I’ll end this post with this.
Be nice.
Your other teams don’t want to be talked down to nor do they want to spin in circles. Help them by creating a clear, effective, and detailed ticket.
You’ll make friends along the way and you may find yourself building SEO advocates.
Happy logging!
