How to document SEO requirements for migrations | Lillian purge

How to document SEO requirements for migrations

From experience, the single biggest reason SEO migrations fail is not lack of knowledge, lack of tools, or even lack of effort. It is lack of documentation. I have seen highly capable teams with strong developers, good designers, and experienced marketers still lose significant organic visibility simply because SEO requirements were never written down clearly, agreed formally, or treated as binding.

In my opinion, SEO documentation is the difference between a migration that protects years of search equity and one that quietly dismantles it. SEO requirements that live only in someone’s head, in a Slack message, or in a half-remembered meeting are not requirements at all. They are wishes, and wishes do not survive tight deadlines or competing priorities.

This article explains how to document SEO requirements for migrations properly, not as a theoretical exercise but as a practical working document that developers, designers, agencies, and stakeholders can actually follow. Everything here is based on real migrations, both successful and disastrous, and on years of stepping in after launch to reverse damage that could have been avoided with clearer documentation.

Why SEO documentation matters more during migrations than at any other time

SEO is often forgiving during normal site development.

From experience, small SEO mistakes can sometimes be corrected gradually. Content can be improved, links can be added, and structure can evolve over time. A migration is different. A migration is a moment where many SEO signals change simultaneously.

URLs change. Internal links change. Templates change. Rendering changes. Content is merged or removed. Redirects are introduced. Canonicals are rewritten. Crawl behaviour shifts.

When many changes happen at once, undocumented SEO requirements are almost guaranteed to be missed.

In my opinion, migrations compress years of SEO risk into a few weeks, which is why documentation becomes critical.

Why verbal SEO requirements are not enough

One of the most common mistakes I see is relying on verbal agreement.

From experience, SEO requirements are often discussed in meetings, agreed in principle, and then forgotten as implementation begins. Developers work from tickets, designers work from wireframes, and project managers work from scope documents.

If SEO requirements are not written into those same documents, they effectively do not exist.

People do not ignore SEO intentionally, they prioritise what is documented and measurable.

SEO documentation is not about control, it is about clarity

Some teams resist SEO documentation because they see it as restrictive.

From experience, good SEO documentation does not dictate how to build something, it defines what must be true when it is finished. It sets non-negotiable outcomes rather than prescribing every technical detail.

For example, saying all existing indexed URLs must redirect one to one to the most relevant new URL is a requirement. How that redirect is implemented is a technical choice.

This distinction is important because it allows flexibility without sacrificing protection.

When SEO requirements should be documented

SEO requirements should exist before design work starts.

From experience, documenting SEO requirements after wireframes or development begins is already late. By then, key decisions have been made that affect crawlability, structure, and content.

The ideal time to document SEO requirements is during migration planning, alongside scope definition and success criteria.

SEO requirements should be treated like performance or security requirements, not optional enhancements.

Who should own the SEO requirements document

Ownership matters.

From experience, SEO documentation should be owned by someone accountable for organic performance, usually an in-house SEO, marketing lead, or external SEO consultant.

Developers should not be expected to infer SEO intent, and designers should not be responsible for defining it.

Clear ownership ensures requirements are defended when trade-offs arise.

The structure of a good SEO migration requirements document

A good document is structured, not overwhelming.

From experience, the most effective SEO requirements documents are broken into clear sections that map to migration phases. They are written in plain language, not jargon, and they explain why something matters where necessary.

The document should be usable by non-SEO specialists without losing accuracy.

Defining migration scope from an SEO perspective

The first section should define what kind of migration is happening.

From experience, SEO requirements differ depending on whether the migration is a domain change, CMS change, platform change, design refresh, or headless build.

Documenting the scope prevents assumptions. For example, a design refresh might still affect internal linking or rendering.

Clear scope avoids dangerous phrases like it is just a redesign.

Documenting URL preservation requirements

URLs are one of the most critical SEO assets.

From experience, SEO documentation must explicitly state whether URLs are expected to remain the same or change.

If URLs must change, the document should state that one to one redirects are required from every existing indexable URL to its most relevant new equivalent.

This requirement should be written clearly and early.

Never assume developers will infer redirect expectations correctly.

How to document redirect requirements properly

Redirect documentation should go beyond saying we need redirects.

From experience, SEO requirements should specify that redirects must be permanent, server side, and implemented before launch.

They should also specify unacceptable behaviours, such as redirecting everything to the homepage or using chains.

Clear requirements reduce creative interpretation that damages SEO.

Documenting canonical behaviour expectations

Canonicals are often misunderstood.

From experience, SEO documentation should define what canonical behaviour is expected post-migration. For example, all indexable pages should self-canonical to their final clean URL.

If there are exceptions, such as pagination or faceted navigation, those should be documented explicitly.

Leaving canonicals to CMS defaults after a migration is risky.

Documenting indexation rules clearly

Indexation rules must be explicit.

From experience, SEO requirements should state which sections must be indexable and which must not.

This includes staging environments, internal search pages, filters, and any duplicated content areas.

Assuming noindex rules will carry over correctly between systems is a common mistake.

How to document rendering requirements

Rendering affects everything.

From experience, SEO documentation should state whether pages must be server side rendered, statically generated, or otherwise fully rendered for crawlers.

If JavaScript is involved, the requirement should state that core content must be present in the initial HTML.

This avoids situations where Google sees an empty shell and delays indexing.

Documenting internal linking expectations

Internal links distribute authority.

From experience, SEO requirements should specify that all important pages must be reachable through crawlable internal links without relying on client-side interactions.

Breadcrumbs, navigation menus, and contextual links should be included explicitly where required.

If internal linking logic changes, SEO must approve those changes.

Documenting content retention and consolidation rules

Content decisions are often where SEO value is lost.

From experience, SEO documentation should state that no indexed content may be removed or consolidated without SEO review and approval.

It should also define how content consolidation should be handled, including redirect and canonical requirements.

This protects against silent deletion of high-value pages.

How to document metadata requirements

Metadata is often assumed.

From experience, migrations frequently launch with missing or duplicated titles and descriptions because metadata logic was not documented.

SEO requirements should state that all indexable pages must output a unique, descriptive title and meta description consistent with the previous site unless intentionally changed.

Defaults are rarely sufficient.

Documenting structured data expectations

Structured data should not be an afterthought.

From experience, SEO documentation should list which schema types must be preserved or implemented.

If structured data existed pre-migration, it should not disappear without reason.

Schema often influences rich results and click behaviour.

Documenting XML sitemap requirements

Sitemaps are part of SEO infrastructure.

From experience, SEO documentation should specify that XML sitemaps must include only canonical, indexable URLs and be updated automatically.

It should also state where sitemaps will be hosted and how they will be submitted.

Outdated sitemaps cause confusion after migrations.

Documenting robots directives and headers

Robots behaviour is easy to break.

From experience, SEO requirements should explicitly state that production environments must not inherit noindex or disallow rules from staging.

This requirement should be highlighted because it is one of the most damaging mistakes.

Do not assume environment separation is handled automatically.

Documenting performance expectations that affect SEO

Performance is not just a UX issue.

From experience, SEO documentation should include minimum performance expectations where relevant, especially for mobile.

This might include requirements around page load time, Core Web Vitals, or asset delivery.

Performance regressions can impact crawl efficiency and engagement.

Documenting analytics and tracking continuity

SEO relies on data.

From experience, migrations often break analytics tracking, which makes diagnosing SEO impact harder.

SEO requirements should state that existing analytics and event tracking must continue uninterrupted post-migration.

Measurement is part of protection.

Documenting Search Console and verification continuity

Ownership continuity matters.

From experience, SEO documentation should include requirements for maintaining Search Console verification, properties, and access.

Losing historical data complicates post-migration analysis.

Search Console continuity supports faster recovery.

How to document SEO testing requirements

Testing should be explicit.

From experience, SEO documentation should include a requirement for pre-launch SEO testing, including crawl tests, redirect validation, canonical checks, and rendering inspection.

This should be positioned as mandatory, not optional.

Testing after launch is damage control.

Documenting go-live and rollback criteria

Launch criteria matter.

From experience, SEO documentation should define what must be true before launch, such as redirects in place, indexation rules verified, and no critical errors present.

It should also define rollback criteria if serious SEO issues are detected.

Clear criteria reduce panic decisions.

How to document post-migration monitoring responsibilities

SEO responsibility does not end at launch.

From experience, SEO documentation should include post-migration monitoring requirements, including tracking indexation, traffic trends, and error reports.

It should also define who is responsible for fixes during the stabilisation period.

This avoids finger pointing later.

Writing SEO requirements in language developers respect

Tone matters.

From experience, SEO documentation should be written clearly, concisely, and respectfully. Avoid vague warnings or absolute claims without explanation.

Explain the impact of non-compliance where necessary, such as loss of organic traffic or delayed recovery.

Developers engage better when requirements are reasoned, not dictatorial.

Avoiding over-documentation and noise

More is not always better.

From experience, bloated SEO documents get ignored. Focus on requirements that genuinely protect search equity.

Nice to have suggestions should be separated clearly from mandatory requirements.

Clarity increases compliance.

Using acceptance criteria to enforce SEO requirements

Acceptance criteria are powerful.

From experience, SEO requirements should be translated into acceptance criteria within project management tools where possible.

This ensures SEO is checked before tickets are closed.

SEO should be part of definition of done.

How to handle pushback on SEO requirements

Pushback is normal.

From experience, time, budget, and complexity pressures often lead to attempts to bypass SEO requirements.

Documenting requirements gives you something objective to point to.

It shifts discussion from opinion to agreed risk.

Keeping SEO requirements versioned and updated

SEO documentation should be a living document.

From experience, migrations evolve, and requirements may need adjustment.

Version control and change logs help maintain clarity.

Untracked changes create confusion.

Educating stakeholders through documentation

Documentation educates.

From experience, good SEO requirements documents help non-SEO stakeholders understand why certain things matter.

This reduces future resistance and improves collaboration.

Education is a long-term benefit.

Why undocumented SEO decisions always resurface later

What is not written down is forgotten.

From experience, undocumented SEO decisions resurface months later as unexplained traffic loss or ranking decline.

At that point, nobody remembers why a choice was made.

Documentation preserves institutional memory.

The cost of not documenting SEO requirements

The cost is rarely immediate.

From experience, the cost appears as lost revenue, slow recovery, reduced trust, and firefighting.

Fixing undocumented mistakes costs more than preventing them.

SEO documentation is insurance.

Final reflections from experience

From experience, knowing how to document SEO requirements for migrations is one of the most valuable skills in digital marketing.

In my opinion, migrations do not fail because teams lack expertise, they fail because expertise was never written down in a way others could act on.

Clear SEO documentation protects visibility, aligns teams, and turns migrations from risky events into controlled transitions.

If there is one principle to remember, it is this, if an SEO requirement matters, it must be written, agreed, and enforceable.

Everything else is hope, and hope is not a migration strategy.