Why SEO Documentation Fails
Why SEO documentation fails to get SEOs & developers on the same page
The SEO Sprint is a weekly newsletter that provides practical advice for SEOs on how to work with product and development teams.
SEO documentation can often fail to get across what we want from developers.
Interestingly, when I was training as a Product Manager I discovered a mental model that change how I work with development teams.
That mental model is called Shared Understanding.
Shared understanding now helps me understand when development, product or business stakeholders can misinterpret or misunderstand written documentation.
It also helps me better understand how to get across my recommendations to development teams, so are on the same page about the SEO feature or recommendations.
In this newsletter we are going to cover:
Why does SEO documentation fail?
What is shared understanding?
What are the benefits of shared understanding?
What does shared understanding look like in organisations?
Why can SEO documentation fail?
The SEO industry relies on written documentation to communicate recommendations.
The problem is that when we pass these documents across to development and product teams, they either:
Interpret what you’ve written differently or,
Skim-read the document without actually taking it in.
Let me give you an example.
I had a conversation with a developer recently that went like this:
“Developer: The change has been implemented on staging.”
“Me: I’m testing the changes and it seems the h1 tags have been updated, not the title tags?”
“Developer: Oh, I thought the ticket was about h1 tags? I’ll make the change.”
“Me: Not a problem, yep I can see the title tags have been updated, thank you”
SEO teams work hard to make sure tickets are as clear as possible. Yet, even when tickets are clear to avoid misunderstandings, the opposite can happen.
The example I gave is an easy fix. But, the more complex the project the greater the impact misunderstandings between team members can have on a project.
For example, when building a new feature from scratch it is imperative that a product and engineering team get on the same page. Otherwise, teams can waste time working on the wrong things.
The goal of an SEO team is not to write perfect documentation but to work with development and product teams to build shared understanding.
🧠 What is shared understanding?
The definition of shared understanding is straightforward:
“It is when people understand what other people are imagining and why.” - Jeff Patton
Share understanding means that a team has a shared mental model of:
What problem they are trying to solve
Who they are trying to solve it for
Why they are trying to solve it
The goal of shared understanding is to make sure that team members have the same mental model of the problem and why they are trying to solve it.
🤝 How do teams build shared understanding?
There are two key ways that teams build shared understanding:
Form teams - Create squads of specialists who can complete the project
Build team walls - Create team walls to drive the conversation
Working in smaller groups to build shared understanding is critical. The more people you try to bring into the conversation the harder it will be to stay focused on one problem.
I don’t want to focus on this section too much as I’ve already covered the role of team structure in the following newsletters:
Build Team Walls
The most common method of building shared understanding within organisations is to create a team wall.
For example at product organisations like Atlassian and UK Government Digital Service (GDS), teams build shared understanding by sketching, writing on sticky notes, and drawing diagrams. Then crowd around the walls to discuss ideas and the next steps in the project.
At DeepCrawl we did the same thing. The team built shared understanding by creating a wall where we sketched, wrote on post-it notes and got on the same page around features.
I've used the same techniques I learned at DeepCrawl to build a shared understanding within client engineering and product teams around SEO features.
Below is an example of a team wall from a FinTech client for a new feature I worked on as a freelance SEO Product Manager.
Below is another example of a team wall for a SaaS client to restructure their website architecture in the backend.
The team use this wall to collaborate and share ideas using designs, sketches and post-it notes. It helped get engineers, designers and product managers on the same page.
Although it looks very messy from the outside it’s actually clearing up the uncertainty/confusion in a team's collective mind.
📄 Is SEO documentation a waste of time?
No. Quite the opposite.
Good SEO documentation helps enable good conversations. The conversation and questions around the documentation between people build a shared understanding.
Good documentation allows us to remember those conversations.
Jeff Patton explains that good documentation is like a “vacation photo”:
“What’s most important isn’t what is written down — it’s what we remember when we read it. That is the vacation photo factor.” - Jeff Patton.
Below is a picture of my friend Sam at BrightonSEO in April 2022. We hadn’t seen each other face to face in years due to the pandemic. So, at the conference, we had a catch-up.
This is what I see in this picture:
Sam - I can remember chatting with Sam as we waited in line for a coffee. I remember us sitting down at an empty table behind Orit (who I didn’t clock at the time). I can recall us discussing everything from work, the SEO industry and what was going on in our lives.
SEO & Dev chat - I can also remember speaking to in-house SEO in that cafe in the corner of the photo, hours before meeting Sam.
Orit - I imagine Orit can recall the conversation she had with one of her colleagues in that cafe (it looked like an official SEO business).
If you were at BrightonSEO in April 2022 and you look back at pictures on your phone you can also recall events and conversations you had with people in the industry you hadn’t seen in years.
This is the goal of good SEO documentation (audits, tickets, strategy docs, etc.). It helps us remember the conversations we have with other team members around a feature or recommendation.
The shared understanding from conversations, discussions and meetings helps fill in the detail when we look at SEO documentation.
⚖️ Benefits of shared understanding
From my own experiences, the benefits of building shared understanding within a team are:
😕 Reduces misunderstanding
Shared understanding reduces the misunderstanding of what different specialists are working on and why they are working on it.
This can help stop development or product teams green lighting a project only to turn around a few weeks later and state “actually we can’t do 70% of what we said we could do”.
⏰ Reduces wasted time
It reduces the time needed for individuals to get on the same page about a complex project and helps teams hit the ground running on solving a problem.
⚙️ Highlights technical feasibility
Shared understanding will help uncover whether the problem has a realistic and feasible solution which can be shipped quickly.
🚨 Technical Word Alert 🚨
The term technical feasibility just means “can we technically do this with the resources at our disposal”.
Development teams need to get a good grasp on what you need from them to provide you with their best guess if it’s feasible or not.
🚨 Technical Word Alert 🚨
😵 Reduces unnecessary complexity
Share understanding helps teams to break down big things, into smaller things which can be worked on by the team and get released faster.
🐛 Reduces defects
Shared understanding helps technical teams understand the assignment and build something that is in line with expectations of what is in the mind of the other individuals in the team.
🚨 Technical Word Alert 🚨
A defect is when a piece of code is released in an Agile iteration that does not meet the “criteria” in development tickets. This means the devs released something that isn’t exactly right or what was discussed with business stakeholders.
This happens a lot if teams don’t speak to each other and can really slow down the development teams working on new features, as they have to stop and work on fixing things.
🚨 Technical Word Alert 🚨
🏗️ How to build shared understanding
The best ways I’ve found to build shared understanding include:
Shared virtual space
Draw, sketch and visualise ideas
Schedule productive meetings
🌌 Shared virtual space
Online whiteboard tools allow you to create a virtual wall where your team's ideas can be kept.
Miro is one of the all-time favourite tools I’ve kept from my product management days, and I would highly recommend it to anyone who hasn’t used online whiteboard platforms.
I’ve been using Miro for the last 3 years and the product helps me:
Create diagrams, low-fidelity designs or upload images
Collaborate with different teams by sharing the virtual wall
Capture questions or ideas on post-it notes
Create templates to jump into discussions quickly
Create collaborative meetings with specialists around the world.
Think about how you can use whiteboarding tools to collaborate within your team.
If your team is already using a specific tool then use that to start with, don’t try to battle adding a new tool to an already steep uphill climb.
Practice sharing and collaborating on small projects or tickets first, then build to larger projects.
✏️ Draw and sketch ideas
One of the best ways to spark conversation and discussion around your recommendations is to envision ideas for others to see what is in your mind using examples.
There are three key ways I have found you can envision your ideas:
Work with the designer
Sketch or draw low-fidelity design
Create diagrams or tables
Remember the point of what we’re doing is not to create perfect solutions or designs (in fact the lower the fidelity the better) but to help build a shared understanding within the team.
Draw, sketch and use diagrams as a way of making clear the outcome you want from the development or product team.
Don’t worry about the designs being perfect, in fact, the worse they are the better as it means teams aren’t threatened by your amazing design skills.
Use tools like Excalidraw to create really rough sketches or diagrams.
Never underestimate the power of creating a simple table in Excel or Google Sheets with pass/fail scenarios as examples.
📅 Scheduled meetings
One key aspect of building shared understanding is getting the right people in the room (real or virtual) to discuss your recommendations.
Most product and development teams won’t join extra meetings because of a lack of an agenda or because they don’t want to waste their time on pointless meetings.
To combat this and build trust with product and development teams I always make sure that any meeting has a clear purpose and goal.
Discuss creating a new weekly meeting with the manager of the development team, and then the developers themselves.
Always make sure the meeting has a clear agenda and purpose which is shared with the team.
Ensure the tech lead or the developer doing the work is present, if the developer is not present then shared understanding is not being built.
Keep the meeting short and concise, it should only be 30-45 minutes long (25 -40 mins of discussion and 5 mins recapping and next steps.)
Standardize and experiment with the meeting as part of your team’s rituals, shared understanding requires continuous discussion, not one-off meetings.
When working with development and product teams remember:
SEO documentation can fail - SEO documentation can fail because shared documentation does not equal shared understanding.
SEO team’s goal - The goal of working with development and product teams is to build a shared understanding by having conversations.
Shared understanding - Shared understanding is a shared mental model of what a team is trying to solve and why they are trying to solve it.
Benefits of shared understanding - Shared understanding can help reduce defects, unnecessary complexity and misunderstandings.
Building shared understanding - Using whiteboarding tools and communicating your ideas can help get everyone on the same page.
🛎️ Further Reading
Watch: Why Documents Fail And What You Can Do About It - A talk where Jeff Patton talks in-depth about shared understanding and why technical documentation fails.
Watch: What is shared understanding? - A quick video by Jeff Gothelf that covers shared understanding within organisations.
Read: The role of the agile wall at GDS - A post on how UK Government Agile teams use walls (almost 10 years old post but still good).
📋 Newsletter Feedback
How did I do this week?
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.