SEOs can find it difficult to communicate with development teams.
It can be frustrating and often results in SEO tickets not being implemented properly or delayed due to teams not being on the same page.
Elite product and engineering teams don’t have that problem.
They use a powerful method to communicate complex specifications that both business and technical teams can understand.
That method is called Specification by Example.
It’s a methodology that uses concrete examples as a single source of truth to create development tickets that build both shared understanding and develop a common language across cross-functional teams.
I’ve been using this method for a while now to work with product, development and UX teams to communicate SEO recommendations.
Honestly, it feels like an SEO communication superpower ⚡.
In this newsletter, we’re going to cover:
🤷 What is Specification by Example?
🧱 Abstract Statements vs Concrete Examples
📈 Why should SEOs use Specification by Example?
📐 How can SEOs use Specification by Example?
🧺 Examples of SEO tickets and Specification by Example
📚 Further Reading (link to the book)
🤷 What is Specification by Example?
Specification by Example (SBE) is defined as:
“Specification by Example is a process to define requirements for software by illustrating specifics using concrete examples rather than abstract statements.” - Gojko Adzic, Author Specification by Example
It is a method that is known by many other names in the software world including:
Example-driven development
Executable requirements
Acceptance test–driven development, or
Acceptance testing
Although there are many names for this method, the principles are always the same.
Examples are a single source of truth which can be tested by developers, communicate requirements and create living documentation.
That is it.
This method is used by elite teams across the world to specify, develop and deliver complex software projects in short iterative cycles.
Since I found this method it has been one of the most useful and simple methods to teach others to write effective SEO dev tickets.
Let’s jump into an abstract statement vs a concrete SEO example to get a better understanding of why Specification by Example is so powerful.
🧱 Abstract Statements vs Concrete Examples
Let’s dig into an example to understand the difference between a general ticket and a ticket written using a concrete example.
Abstract statement
An abstract statement is a request which uses a generic request that is copied from SEO tools or documentation.
It requires the developer to “guess” what the product, SEO or business analyst specialist is asking them to do.
This guesswork causes developers to be uncertain about even simple tasks. The greater the uncertainty the greater the chance projects will take even longer to get implemented.
There is no clear way to test this ticket and no clear example to help them figure out what success looks like. It heavily relies on official Google Documentation to inform the developer what they need to do.
Concrete example
A ticket written using a concrete example is easy to understand by a developer.
In the example below, the SEO has taken the list of pages which need to have a self-referencing canonical tag and created a testable example in the form of a data table.
This can then be used to write the acceptance criteria the developer needs to meet so it can be marked as “done”.
Any technical SEO jargon is written in plain English that anyone can understand (SEO, product or dev). Anyone in the team can read this ticket and understand that any coloured dresses page should have a self-referencing canonical tag in the <head></head> of the HTML.
There is little “guesswork” done by the developer or QA team. A developer could take this ticket and easily test it to see if their work matches the acceptance criteria in the request.
📈 Why should SEOs use Specification by Example?
Specification by Example is a method that has been so useful in breaking down complex projects into actionable tickets.
I’ve found that it:
Clarifies Acceptance Criteria 📋 - SEOs can write better specifications and reduce the amount of discovery work needed.
Develops a Common Language 💬 - Concrete examples help cross-functional teams (SEO, product, dev, etc.) quickly develop a common language, reducing the time needed to discuss and discover the tickets.
Builds shared Understanding 🧠 - Concrete examples help the team quickly get on the same page to identify ambiguous or missing requirements in stories.
The great thing about this method is that it is simple and can be applied to any project or ticket.
No matter the size or complexity. In fact, the more complex the request, the more Specification by Example can help an SEO write clear, testable and focused tickets.
📐 How to use Specification by Example?
Below is a process I use to create concrete examples and write specifications for SEO projects.
Note: I’m making the assumption you’ve done some analysis or an audit during these steps and want to communicate your recommendations to development teams.
🔎 Identify Scope
The first step is to make sure you’ve identified the scope of the request, task or recommendation.
I ask myself these four questions:
What is the problem?
What pages are we targeting?
What page templates are we targeting?
What does success look like?
Below is an example from Canva:
What is the problem?
Canva pages are missing self-referencing canonical tags.
What pages are we targeting?
Pages in the https://www.canva.com/solutions/ directory.
What page templates are we targeting?
The “Canva for your business” template.
What does success look like?
Pages in the /solutions/ directory will have self-referencing canonical tags.
Once I’ve answered these questions I move on to gathering examples to show what success looks like to the development team.
⚡ Gather Examples
Next, we gather examples to show what success looks like to other stakeholders in the team.
There are two key methods for gathering examples:
SEO Data - Use SEO data or documentation to identify examples from SEO tools
Designs - Visualise ideas using designs, tables or diagrams
There is no right or wrong way to go about this but just remember the golden rule:
Examples are the single source of truth that is testable by developers.
Whatever method you use, try to make sure that the examples can be used to show what success looks like and can be marked as either pass or fail.
SEO Data Example - Self-referencing canonical tags
For example, for the self-referencing canonical tag example, I would pull key examples from the SEO crawl data to get across my point into a small table. Then I would write the HTML for the self-referencing canonical tags I’d expect to see using Google’s official documentation as a guideline.
Designs Example - Pagination Link Scheme
For example, you can use sketches, and low-fidelity or high-fidelity designs to create visual models to show what success looks like to the development or product team. I’ve used them all from a client sketching out his idea on an A4 piece of paper to using a designer to build out a design system for a new set of Fintech application reports.
I’ve used Excalidraw to draw really bad designs low-fidelity pagination link scheme designs to communicate the expected outcome to a dev team. It helped to get everyone on the same page very quickly and I was able to use it in the ticket to building shared understanding.
📝 Illustrate and Write Specifications
Finally, we use the examples from the SEO data and designs to write the specifications.
Before we write any specifications it is important to understand two critical parts of Specification by Design:
Specification principles 🧠
Testable scenarios 🧪
🧠 Specification Principles
When writing specifications and illustrating examples it is important to keep in mind these five key principles:
Every task or ticket needs to be self-explanatory
Every task or ticket needs to be focused
Every task or ticket needs to be a specification, not a book
Every task or ticket needs to be in a common language
Every task or ticket needs to be testable
These principles can be used to write a request or development ticket using the concrete examples we’re gathered.
Example - Abstract statement into specific rules
For example, we can turn the abstract statement into a concrete example.
Please add self-referencing canonical tags to any pages in the https://example.com/dresses directory.
Instead of trying to write “generic statements” copied from SEO tools/Google’s documentation, instead, we use our concrete examples to write specific and clear specs that anyone can follow:
🧪 Testable scenarios
When using concrete examples it is important to frame them as scenarios.
A scenario is an example of a system’s behaviour that can be tested from the perspective of a user.
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
The concrete examples you’ve gathered are the scenarios. They are the specific use cases which can be used by the development team to test the request or ticket.
The illustration of choice for me is the data table. One of the best ways to illustrate advanced technical outcomes to the development team.
It’s these specific scenarios the examples which can be used to test the task throughout the lifecycle of a ticket or project.
🧺 Examples of SEO and Specification by Example
Below are more examples of different ways I’ve used Specification by Example to communicate recommendations to development teams.
Both inside and outside ticketing systems.
Hreflang Tag
Internal linking module
Pagination link design
FAQ Schema Markup
Smaller XML Sitemap Files
🎉 Bonus Tips!
Below are a few tips to keep in mind when using Specification by Example for SEO projects.
This document can then be read by your team before jumping into an online whiteboard tool to discuss scenarios, examples and rules around your tickets.
Specific Testable Scenarios 🥼
I’ve found the best scenarios are specific, not generic.
When a development implements an SEO ticket they need to be able to use the scenario to test whether the ticket has passed or failed.
This means trying to be focused as much as possible with your scenarios and really narrowing down what you expect from the ticket.
Formatting Tickets 🎟️
A lot of development and product teams have strong opinions about writing development tickets.
The truth is I wouldn’t worry too much about the format of the ticket or request. Every team, company and individual has their own template.
I’d focus on writing simple and clear sentences that can be understood by other stakeholders. A good way to ensure this is to use bullet points.
I’ve given a few more tips on writing tickets here.
1 Scenario = 1 Action 🧨
A good rule of thumb I have found is that 1 scenario is usually an indication of the user doing one action.
In SEO this means that Googlebot fetches and downloads a page and views a self-referencing canonical tag = 1 action.
The more actions a development ticket has the greater the complexity you’re asking the developers to implement. Remember, keep things simple but valuable to the user.
This is super hard and takes practice.
2-3 Scenarios per dev ticket 🔢
Any example is not limited to 1 scenario.
However, I’ve found a good rule of thumb is 2-3 scenarios per ticket.
If you’re gathering more than 3 examples for one ticket then this is a good indication that the ticket needs to be broken down into smaller chunks.
Use to discuss complex projects 🗨️
Even simple tickets can be complex.
Use Specification by Example to build a common language and shared understanding around your SEO projects.
This means there will be questions, discussions and debates on what needs to be implemented. This is good.
Concrete examples help spark discussion around tickets and help everyone get on the same page.
Think outside the box for examples 📦
I’ve listed some of the ways I show examples but these are just the ones I use most often.
Think of your own examples you use to communicate with other teams. For example, Aleyda Solis at #SEOFOMO uses flow charts to communicate expected outcomes around certain problems.
A flowchart like this would make a great concrete example (combined with SEO data) of the expected result you wanted to achieve.
Examples can be as creative or as simple as you want them to be.
📌 Summary
The Specification by Example method can help SEOs:
Specification by Example (SBE) - This is a process of writing specifications by using concrete examples and not abstract statements.
Examples are a source of truth - Which can be used to validate specifications requested by developers and write tickets that can be understood by multiple stakeholders.
Benefits of SBE - The benefits of Specification by Example is that it quickly helps develop a common language and shared understanding in cross-functional teams.
SEOs can use SBE - SEO teams can use Specification by Example principles and scenarios to write clear SEO tickets that create certainty in development teams.
📚 Further Reading
Read: Specification by Example- The book of 50+ case studies written by Gojko Adzic an award-winning author and software consultant on how successful Lean and Agile teams design, develop and deliver software.
Read:Specifying by examples - An early article written by Gojko Adzic on using concrete examples to create better developer tickets.
Read: How to write Effective SEO tickets - A newsletter by me on how to write effective user story tickets using the principles from Specification by Example.
