⚡ Specification by Example and SEO

• Read original article here

A weekly newsletter that provides practical advice for SEOs on how to work with product and development teams.

If you want to help improve The SEO Sprint please feel free to leave feedback!

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 calledSpecification by Example.

It’s a methodology thatuses concrete examples as a single source of truthto 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:

Specification by Example (SBE) is defined as:

It is a method that is known by many other names in the software world including: 

Although there are many names for this method, the principles are always the same.

That is it.

This method is used by elite teams across the world to specify, develop and deliver complex software projects inshort iterative cycles.

Since I found this method it has been one of the most useful and simple methods to teach others towrite effective SEO 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.

Let’s dig into an example to understand the difference between a general ticket and a ticket written using a concrete example.

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.

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

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. 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. 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 pages are we targeting? What page templates are we targeting? What does success look like? Below is an example from Canva: What pages are we targeting? 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. 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 There is no right or wrong way to go about this but justremember 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 eitherpass orfail. 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. 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. 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: 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. 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: 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 theBDD 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 thescenarios. 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. Below are a few tips to keep in mind when using Specification by Example for SEO projects. As I mentioned in writing SEO effective tickets a good way to get feedback from other teams is todocument and share your specifications for an SEO project. 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. 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 haspassedorfailed. This means trying to be focused as much as possible with your scenarios and really narrowing down what you expect from the ticket. 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 ticketshere. 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. 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.  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#SEOFOMOusesflow chartsto 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. 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. 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. 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. If you enjoyed reading this article then consider the following: ???? Share— Please share the newsletter with your network or colleagues if you think they might find it useful! ✉️ Subscribe to The SEO Sprint newsletter— if you haven’t already then please consider subscribing to the newsletter. turn on JavaScript This site requires JavaScript to run correctly. Please turn on JavaScript or unblock scripts