It is the team's job to focus on the different ticket types that will maximise output and drive business results. This is usually epics and user stories ticket types.
For now, we will focus on how to write user stories.
Why?
Well, user stories make up the backbone of most development backlogs. They are also the most used ticket type to communicate requirements and specifications to development teams.
❓ Why do User Story Tickets Matter?
A dev ticket is a critical “baton passing” point between business and development stakeholders.
A ticket is output from developing a shared understanding of a problem between business and technical stakeholders.
If the ticket isn’t understood by dev teams this can:
Create bugs or defects in the SEO code quality of a website
Delay SEO projects while the team try to understand the ticket
Get SEO projects rejected because it lacks technical feasibility
🧾 What is a User Story?
A user story is a structured, concise and simple explanation of a new system requirement written from the perspective of the end user.
In certain situations, this type of structure is good. It allows product and development teams to focus on the clear ask from their customers.
Yet, in more complex systems this ambiguity can cause many problems:
Uncertainty - If a ticket is unclear this leads developers to be uncertain about what exactly the business stakeholders want once the ticket is marked as “done”.
Complexity - If the ticket is left to the interpretation of the developer they might have an overly complex solution to a problem which can delay projects unnecessarily.
Defects - A ticket that is not clear can cause developers to produce a solution that doesn’t meet what the business stakeholders had in their minds.
In the SEO industry, our technical requirements can be complex.
As well as stakeholder management, it requires internal and external systems to be aligned to make sure search engines can crawl, index and rank content.
It is important we do not tell developers how to solve a problem in their own system. But, it's critical that developers understand and meet our specifications.
Any user story ticket submitted needs to have clear and easy-to-understand specifications. This helps development teams to create solutions which meet our needs.
After a lot of trial and error, I landed on a new way of writing user stories by using acceptance testing.
🧪 Acceptance Testing
The problem with writing user story tickets is that business stakeholders do not quite understand what they want from the dev team.
The focus for many is to try and get “tickets” into the development backlog.
However, many do not take into consideration the full life cycle of a ticket.
A user story ticket is a source of truth through the product development process. It's used in the QA process to “test” if the code released meets the specifications in the ticket.
Quality assurance (QA) testing is a critical part of the web development process. One of the most used methods to test if a ticket meets the agreed specifications is called acceptance testing.
Acceptance testing is defined as:
“A quality assurance (QA) process that determines to what degree an application meets end users' approval. Depending on the organization, acceptance testing might take the form of beta testing, application testing, field testing or end-user testing.”
In other words, acceptance testing is the process of making sure the acceptance criteria in a user story have been met. If the acceptance criteria have been met then the ticket can be marked as done.
How can we use the practice of acceptance testing to evolve user stories?
By using two lesser know software development practices:
These frameworks encourage collaboration by “starting with the end in mind”. They encourage the use of concrete examples as a single source of truth. These examples help to close the gap between business and developer stakeholders.
I’ve found using these frameworks has helped me:
Align teams - Dev and business teams develop shared understanding around ticket specifications
Reduce rework - Devs spend less time going back and fixing defects.
Improve SEO code quality - The dev team is producing higher SEO code quality in each release
It is these practices that have helped me craft effective user stories.
✍️ How to write effective user stories in SEO
I use a 6-step process to write SEO tickets/user stories for a new SEO project. In the next section, I am going to take you through it.
Before writing any tickets, we need to gather concrete examples of the output we want from the ticket.
In the SEO industry, we have access to tools, playbooks and checklists that help uncover real-world examples. So, do what you normally do when uncovering SEO problems.
However, when gathering examples think about:
Output - What is the desired outcome we want to achieve if we fixed the problem?
Scope - What is the scope of the problem you want to solve (page template, URLs, CMS, etc.)
Visuals - How can we visualise using diagrams, tables or data the desired outcome?
Let’s use some examples to show you how to do it.
Example: Canonical Tag - Canva
Canva is a large website with a number of product-led page templates that capture traffic for different use cases. One of those use cases is “Canva for your business”.
In a hypothetical scenario, let's say these business templates did not have a self-referencing canonical tag. The SEO team have identified that duplicate pages caused by tracking parameter are being indexed, causing issues with the SEO performance of the pages in the https://www.canva.com/solutions/ directory.
As part of the technical recommendations, the SEO team have identified that the dev team can add self-referencing canonical tags to the page templates.
The SEO team now have everything they need to construct an example:
Output - They know they want a rel=canonical tag present in the HTML and rendered HTML
Scope - They know that the problem is isolated to pages in the /solutions/ directory
Visuals - The SEO team created a small table (below) and gathered a list of all the pages that need the canonical tag.
User stories tickets lack visuals to help dev teams clearly get what business stakeholders are after. A simple table like the one below can outline what is expected from the dev team.
Using tables likes this can provide a concrete example that the development team can understand.
🔢Step 2: Write Scenarios
Once you’ve identified the concrete examples you can now start to get a better understanding of how the ticket can be tested.
In BDD the way that engineering, business and QA teams are trained to understand if the ticket can be marked as “done” is to use scenarios.
A scenario is defined as:
“A scenario is an example of the system’s behavior from one or more users’ perspectives.” - Liz Keogh
BDD teaches teams to use real-world examples to help them understand what to expect from the system. In many products, SEO and development teams the opposite happens. We try to write the technical specifications before anything else.
It is by using real-world examples that teams can build a shared understanding of whether the team understands the ticket.
Before I start to write the technical specifications I start with writing the scenarios based on concrete examples.
I use the following format when writing scenarios (taken from the BDD testing framework):
Scenario – The name for the behaviour that will be described
Given – The beginning state of the scenario
When – Specific action that the user makes
Then – The outcome of the action in “When”
And – Used to continue any of three previous statements
When writing a scenario remember to make it specific. It should be a real-world example that can be tested on the website and have real data when the ticket is implemented.
A generic scenario is just another way of writing acceptance criteria.
🧠 Quick Note 🧠
You don’t need to write down scenarios for every acceptance criteria in a ticket if they are clear but I would recommend writing down scenarios to help communicate the real-world example to test the ticket.
If you’ve written more than 2-3 scenarios for a ticket it might be a sign that the ticket is too big. Which is good! That means you might have to chat with your dev team about chunking your recommendations into a series of smaller user stories.
🧠 Quick Note 🧠
Example: Canva Scenario
The SEO team at Canva can write a quick scenario based on their real-world example to communicate what is expected once the ticket is implemented:
Scenario #1: Search engine bot crawls and picks up a canonical tag on Newsroom Business page
Now, you’ve written down your examples and scenarios it is time to write down your specifications in a user story ticket (widely known as acceptance criteria).
What are the acceptance criteria? They are simply a set of clear pass/fail statements in a ticket.
That’s it.
Source: AC are a clear set of pass/fail statements
When a development team is testing the ticket each statement should either be pass or fail. There can’t be any “in-between” states. This helps make sure that your tickets are concise and to the point.
I always use bullet points when writing them down and follow these best practices:
AC is self-explanatory - The AC should be easily understood when someone looks at the ticket.
AC is testable - The AC should be testable either using an automated or manual process.
AC is achievable - The AC should be achievable within a couple of days or 1 Sprint at maximum.
AC reaches consensus - The AC should be agreed on by the delivery team (it’ll never be 100%).
AC fills in blanks - The AC should “fill in the blanks” for content, wording or design.
AC is broad - The AC should focus on the behaviour change expected from the system.
A few quick tips on writing acceptance criteria to try out:
Use the active voice - The AC reflects the words the user would say in an active voice.
For example:
❌ Passive: Canonical tag should be implemented on the product page
✅ Active: The search bot can crawl and view the canonical tag on the product page
Avoid Negative sentences - Avoid the word “not” in AC and other negative words.
Write Simple Sentences - Avoid using complex sentences that use conjunctions (but, and, so, etc).
Finally, it is time to write the description for the ticket.
The most common format teams use is the Connextra card template (As a...I want...So that) written from the perspective of the user which helps clarify why the ticket is being created.
As a <type of user> → The WHO
I want <to complete a goal> → The WHAT
So that I can <some reason> → The WHY
Although Agile literature online states this is a critical part of writing user stories, the reality is most teams don’t even bother.
There are various reasons why this happens but it's usually because user story tickets are not stories about users but instead a task for a dev to complete.
I don’t want to go down the rabbit hole of why this is bad practice because it is outside the scope of today’s newsletter.
All you need to know is that when writing descriptions use the Connextra card template (As a...I want...So that) but don’t spend too much time on perfecting it.
All the technical team will focus on is the acceptance criteria (which you’ve spent most of your time writing).
Example: Canva Self-referencing Canonical Tag
The SEO team at Canva can quickly write a description for the ticket below based on the AC, scenarios and examples.
As a search engine bot,
I want to be given clear canonicalization signals,
So that I can show the canonical URL in search engine results.
📃Step 5: Capture tickets in an accessible document
Once you’ve followed steps 1-4 you’ll want to capture them somewhere they can be shared with your development or product team (don’t add them to Jira just yet).
In product teams, they capture user stories by adding the specifications and requirements in a Product Requirement Document (PRD) or one-pager. An example of a Shopify PRD is below:
I’ve found doing the same for SEO projects is a good “mid-step” between creating user story tickets, discussing them with tech teams and actually adding the tickets to the development backlog.
Source: SEO User Story Template
Once you’ve gone through all the tickets you want to create you should have a long list of SEO tickets in a document that you want to get implemented by the dev or product team.
Now it is time to have a conversation with them armed with your examples, scenarios and specifications.
🗣️Step 6: Align with the product and development team
I’ve used Miro to clarify tickets with tech teams for years. These conversations always highlight something I’ve missed when speaking to developers, designers or product teams.
Source: Miro Board where tickets are discussed/negotiated with dev team
Both from my own experience and interviewing 15 in-house have found that SEO and developer collaboration significantly increases the chance of tickets being implemented.
When writing down your tickets and then explaining them to development teams face-to-face, forces you to think through the problem using real examples. From these examples and scenarios, you can start to identify knowledge gaps.
This means that your tickets will change based on the discussion with the development or product team which is a good thing.
The discussion will mean that you’ll be aligned on what can be achieved.
