Luca Mussari

Luca Mussari

Copyright © 2024

Luca Mussari. All rights reserved.

5 Tips For Writing SEO User Stories for Websites (With Examples)

When embracing Agile methodologies for SEO, user story writing can seem hard at first glance. Learn more about how to craft awesome user stories and what to avoid when writing them.

I’ve talked in-depth about user stories and why they are one of the greatest tools to bridge the communication gap between yourself (as an SEO professional) and your engineering team.

As a quick recap, a user story is a tool used in Agile methodologies such as Scrum and Kanban, which allows product owners to describe a feature or functionality from an end-user point of view in a brief and informal way.

It generally includes a value statement (i.e. “As a … , I want [or need or can]… so that…”) and can be expanded with the inclusion of acceptance criteria or other additional attachments such as designs, user flows, prototypes, and other useful information.

But what should you look for when writing user stories and how can you make sure you’re writing them in a clear and effective way?

In this post, I’m going to talk to you about 5 things you should consider when compiling user stories and I’ll also provide some examples of full user stories for SEO (yes, you can thank me later 😛 ).

1. Get Your User Value Statement Right

The first thing you want to get right when writing a user story is the user value statement. In product management, as the name suggests, the user value statement must be exclusively built with the user in mind. It shouldn’t be really thought of by the software engineer or, worse, from the product owner’s perspective.

This is the rule of thumb that should be also followed when writing Agile stories in the context of search engine optimisation. Product owners for SEO, in fact, should always think of the final goal users will achieve when creating a certain feature or functionality.

For example, let’s say you are writing a user story about implementing product schema markups across your eCommerce product pages. The trap you might fall into is to focus your value statement around the fact that using structured data will provide more clear information to search engines so they can better understand your content. That is indeed true and is with no doubt the reason why you might want to implement schema markup but, when you actually look at it from a user perspective, you realise that the actual goal of implementing this feature is to enable rich results so that users can immediately find product information directly in search results or image results. And this is the angle your user statement should be looked at.

Writing user stories from the user perspective

That being said, there are some exceptions to this rule of thumb in the world of SEO. In addition to the user, in our case website visitors, there is also an additional end-user type: web crawlers or spiders.

Thanks to sophisticated applications of machine learning in their algorithms, search engines are becoming increasingly smarter in interpreting user behaviour and satisfying searcher intent. Nonetheless, their bots still need additional hints to be able to effectively crawl, render, and index content on the web. And for this reason, you might find yourself in the position of creating features such as automated XML sitemaps that are primarily built around facilitating the crawling process for search engine bots. In that case, your user story will be written from the search engine’s perspective and might be closer to something that looks like the below:

As a search engine spider/crawler/bot (type of user)
I want to quickly find all the pages that are available for crawling (achieve a goal)
So that I can offer the best possible results to online searchers (reason why)

2. Be Specific With Your Acceptance Criteria

The Acceptance Criteria refer to a set of predefined requirements that must be met in order to mark a user story as complete. Hence, they are also referred to as ‘Definition of Done’ or ‘Conditions of Acceptance’.

Product owners generally write acceptance criteria and then discuss and agree upon them with two key members of Agile teams who better know the technology stack and the feasibility of features: a technical product owner (or usually a member of the development team) and a tester (normally a member of the Quality Assurance or QA team). Those three key people, in Agile defined as the ‘Three Amigos’, usually review the requirements and identify all the potential risks from a business, development, and testing perspective together. In some instances, this three amigos session can also be extended to other participants such as producers, designers, or even product managers, based on the degree of involvement those team members have in creating a certain feature.

So what should I include to get those acceptance criteria on point?

In order to have well-written acceptance criteria and tick all the right boxes, you should make sure to include:

  • the business value of this feature will bring
  • all the potential scenarios you can think of, for which users (or search engines) might use that feature
  • what should happen when they use that feature in all the different scenarios
  • any potential risks you are aware of before the development of that feature
  • any agreed technical requirements that the Technical Product Owner has suggested
  • any agreed testing solutions that have been suggested by the Tester or QA team
  • any user flow, mock-up designs, or prototypes if available or if necessary to show a visual representation of that feature
  • any other useful resources that might help the engineering team to understand more about how that feature will be used and why it’s important for users and search engines

The risks of including vague acceptance criteria and missing most of the elements listed above are that you might compromise your release and potentially waste both time and money.

Clear and unclear acceptance criteria

Clear vs Unclear Acceptance Criteria (Image by

3. Get Clarity On The Effort Required

Similarly to the acceptance criteria, the effort required by the development team to deliver a user story should be specified upfront and never after the development stage has started.

Product owners, QA testers, and developers should all be clear on how much time, development, and budget will be needed to deliver a user story.

The challenges SEO product managers can face if this step is skipped is to get extra effort required to complete this feature during or even at the end of the development. This, in turn, will result in delays or difficult conversations around the budget for SEO product owners.

Generally, software engineering teams working in an Agile environment use story points to measure the effort needed to develop features. Story points are one of the most efficient metrics as it helps both developers and testers estimate the difficulty level of a user story and the business to understand the monetary investment required for that feature. For example, suppose the development team all agree on estimating that user story (e.g. 3 story points). In that case, product owners can generally link this number to a cost per story and get a figure of how much they will be charged for that feature (3 x £1,100 = £3,300).

If you realise a user story requires a significant amount of effort based on the user stories estimation, consider further breaking up the feature into smaller user stories or evaluate with the development team if the user story should be considered its own epic. This might avoid unwanted surprises on the release day or any miscommunications with the dev team during the course of the development process.

4. Agree On The QA And Testing approach

Another mistake you might want to avoid (believe me, I’ve done it myself) is not clarifying the exact process that will be used to test a feature.

Not knowing in which environments the feature will be tested, who will test it, and at which stage of the development, can seriously compromise your technical SEO releases.

In some companies, there might be discrepancies between testing and live environments, and a feature might work correctly in lower environments but not in production on the live website. For this reason, make sure you know who is going to test the feature, and how they are going to do to it, and make sure you offer any support throughout each development stage if needed or even work with them in advance to automate this process if you have the resources to. 

Testing requirementsIf you are interested in testing automation for technical SEO, here is a quite interesting guide about it (please bear in mind that the guide I linked uses DeepCrawl Automator as the main tool, but many other tools could do a similar job. Alternatively, you could even make a case to build your own in-house tool based on your specific needs).

5. Include Additional Resources And Helpful Information

In my experience, I find that providing helpful resources from reputable SEO sources also helps a lot when communicating with software engineering teams.

SEO is a relatively young discipline; as with anything related to the digital space, it has the peculiarity to continuously change.

Therefore, unless you are dealing with software engineers specialising in SEO, it could happen that your developers might not fully capture what you are trying to build and why.

Software engineers, though, are by nature particularly curious. When they are not fully familiar with a topic, they would soon go to read any documentation or any other sources available on that matter. Including in the user story links to Google’s official statements, SEO publications, or just statements from reputable SEO professionals who have shared the code from successful releases, will make their life so much easier and they will have a starting point for their personal research.

I usually also find it helpful to add a background section where I provide as much detail as I can on the current issue (if known). For instance, I might mention how many URLs are affected by that issue or which specific component needs to be fixed. Do this only if you are 100% sure of the real cause of the issue. If not, make sure you describe as much as you can the current behaviour on the site to help developers find what the exact cause is and provide the right solutions. You wouldn’t want your engineering team to think that you are doing their job as they are the expert and they certainly know what’s the best solution once you have correctly explained the problem you are facing.

SEO User Story Examples For Websites

There are many formats user stories can have. In this section of the post, though, I will provide a couple of examples of user stories that you can use as inspiration when drafting your own, based on your specific needs. Please treat them more as an example and not as the main source of truth.

The first user story will be about broken links and the second one will be about ensuring text remains visible during webfont load, a tactic often suggested by Google to improve site speed.

SEO User Story With Acceptance Criteria – Example 1

User Story

As a new or existing website visitor
I want to be able to successfully land on my destination page when clicking on internal links on a page
So that I can visit the content I was promised to

Background info

Internal links from one page to another within the same site help Google find pages and understand what the page being linked to is about. They also help users better navigate the site, without the need to refer to the website’s internal search or bounce back to the search results to then type the query in search engines.

On the site, there are currently 570 broken internal links (see the document attached to this ticket for reference).


By fixing the broken internal links, we will offer a greater experience to website visitors, increase traffic to the correct destination pages, and reduce the site’s overall bounce rate.

Solution suggested by TPO

Replace broken links with suitable destination URLs.

Acceptance Criteria

  • Broken URLs included in the anchor text on the attached document must be replaced with the suggested destination URLs
  • All the internal links listed must not return any 4xx error
  • All the destination URLs included in the internal links of the pages listed in the document must not have any JS or a server-side redirection (e.g. 3xx)

Testing approach

All the internal links should be tested on the stage environment before being pushed live. Post-release checks will need to be done using a crawler to ensure no issues are present in production.

Useful Tools and Resources


Ticket attachments

  • internal-links-with-correct-destination-URLs.xls

SEO User Story With Acceptance Criteria – Example 2

User Story

As a new or existing website visitor
I want to ensure text remains visible during the page load
So that I can have a better user experience, especially if I’m on mobile devices with a slow network.


Some browsers hide text whilst web font loads causing what is defined as a flash of invisible text (FOIT). The ‘”flash” can be avoided by showing content to users immediately using a system font initially, then replacing it. This might save several milliseconds of page loading.

Solution suggested by TPO

To avoid showing invisible text while custom fonts load, temporarily show a system font. By including font-display: swap in the @font-face style, FOIT can be avoided in most modern browsers.

The font-display API specifies how a font is displayed. swap tells the browser that text using the font should be displayed immediately using a system font. Once the custom font is ready, it replaces the system font.

Browser support

Not all major browsers support font-display: swap but those that don’t will be in the minority (see

Acceptance Criteria

  • A system font must be used when supported by the browser. Once the custom font is ready, it must replace the system font.
  • When the browser does not support font-display: swap, no further action is needed as the browser will just ignore it

Additional Resources

Final Thoughts

Writing clear user stories can save you a lot of time, resources, and eventually money so you should make sure to tick all the boxes when compiling them.

Make sure you include a value statement from a user perspective (when you can) and be specific with your acceptance criteria. Ensure everyone is also clear on the testing approach and the effort needed to deliver the feature. If you can, always include additional resources, and anything you think is relevant to succeed with your release. And well, good luck with your projects!

Full disclosure: I am not affiliated with the tools or the publications mentioned in this article.– c

Book Your 1-Hour SEO Consultation