Before moving SaaS documentation to new URLs, test the old-to-new mapping against the answer each old page provided. A successful redirect is only one part of the check. The destination must also contain the relevant documentation, use the intended URL, and work for a reader arriving from an old link.
Treat the mapping as a release artifact with an owner and expected results. Do not leave it as a spreadsheet that someone reviewed once. A route can return a valid response while taking a developer to the wrong product version or a generic docs homepage.
The workflow below is an editorial and engineering test plan for a fictional docs migration. The paths are examples, not observed results from a real site.
Define what is moving
Suppose a company moves guides from /help/ to /docs/. Its team also wants to rename sections and combine a few articles. These are separate decisions. Record the path change, the content change, and any version change in separate columns so a reviewer can tell what each mapping means.
Start with a written scope: which hostnames and paths are involved, which product versions remain supported, and which pages must stay at their current addresses. Include images and downloads when they are part of the documentation experience. A route inventory that ignores linked examples can leave an otherwise readable guide broken.
Google's site-move documentation recommends preparing a URL mapping and testing the new site before moving. It also covers permanent redirects and monitoring old and new URLs. Use that as the search foundation, then add checks for your application's actual docs behavior.
Build an inventory with reasons
Combine the current published page list with useful evidence from your own analytics, link records, and server logs. Note which source found each URL. A page with little recent traffic can still be linked in a customer setup guide or an old SDK readme, so traffic alone is not a deletion rule.
Give every old URL a disposition: unchanged, moved, merged into a relevant replacement, or deliberately removed. Assign an owner to unresolved rows. A blank destination should mean “needs a decision,” rather than quietly becoming a redirect to the homepage.
Record why the chosen target is useful. For example, /help/export-csv might map to /docs/reports/export because that page still explains the CSV export task. The reason is content correspondence. It is not merely that both paths contain a reporting word.
Write the expected reader outcome
Add an acceptance note to each important row. For the export guide, it might say that a reader can find the CSV steps for the current product and identify the plan limitations. This note gives the content reviewer something more precise than a green status code.
Separate old-version documentation from current instructions. If an old URL served version one, sending it to a version two page may be confusing even when the feature has the same name. Decide whether to preserve an archive, explain the version boundary, or provide a relevant transition page.
Do not manufacture a replacement when the old task no longer exists. Document the removal decision and the intended response. Search preservation is not a reason to promise an unsupported feature or disguise an unrelated landing page as documentation.
Check redirects before following them
For each moved route, first inspect the initial response and its destination. Then follow the route to its final page. These checks answer different questions: whether the old route has the intended move response, and whether the full journey reaches the expected content.
Flag loops, unnecessary intermediate hops, unexpected host changes, and destinations that fall back to a generic page. Test at the layer that serves public traffic. A framework route can look correct locally while a hosting rule takes precedence in the deployed environment.
Include representative variants only where they exist in your inventory or routing rules: trailing slashes, encoded characters, case differences, and meaningful query parameters. Do not invent a huge matrix of hypothetical URLs. Use the actual system's behavior to choose the cases that could change the reader's destination.
Test rule collisions
A broad redirect rule can override a specific mapping. In the fictional move, a rule that sends everything under /help/ to /docs/ might swallow the dedicated export target. Test a specific route, a nested route, and an intentional exception against the final deployed rule order.
Pay special attention to routes created after the inventory was collected. Freeze the relevant publishing changes briefly or establish a clear process for adding new rows. Otherwise, the team can launch a map that was complete on Monday and incomplete by Friday.
Review two-way conflicts as well. The old server should not redirect to a new path that redirects back through a compatibility rule. Keep the intended destination written in the test record so a chain cannot pass simply because it eventually returns some successful page.
Verify content and page signals together
At each target, check the visible heading, relevant instructions, product version, navigation, and essential assets. A matching title alone is weak evidence: an empty article template can still display the correct title. Ask a reviewer to complete the original task using the destination page.
Google's migration guidance also covers updating internal links, canonicals, and sitemap entries to the new URLs. Check those signals against your approved destination list. A move is harder to reason about when the navigation uses a new path but the page identifies an old path as preferred.
Keep these checks distinct in the release report. “Redirect passes” should not imply “content reviewed.” Give route handling, content correspondence, and page signals their own outcomes. That makes failures easier to assign and prevents one green column from hiding a missing review.
Set launch gates that someone can act on
Classify failures by their effect on a real task. A broken authentication setup guide may block the release. A cosmetic spacing issue on a low-use archive page may have a different owner and deadline. Agree on the classification before the launch review so the team does not improvise under time pressure.
For each blocker, record an old URL, expected target, actual result, environment, test time, and owner. Include a short reproduction note. A report saying “redirects broken” is much less useful than a row showing the exact route and incorrect destination.
Retest a fixed rule against the cases it can affect. Do not only recheck the single URL that first failed. A change to a broad path matcher can repair one destination while damaging several exceptions.
Prepare the recovery plan
Save the approved map and the released routing configuration together with the release record. Identify who can correct a mapping and who can decide to pause the move. A recovery plan should explain the action available, rather than assume that restoring yesterday's files will reverse every external effect.
For a large move, consider a limited section when that fits the architecture and business constraints. Keep the limitations clear: a quiet section can validate routing mechanics without representing the entire site's search response. It is a test of a defined scope, not proof that every later page will behave the same way.
Monitor the old routes after launch
Review requests to old URLs, redirect failures, unexpected destinations, and reports from readers. Compare the old and new page groups in your search and analytics tools. Annotate the move date and any later fixes so the team can interpret changes with context.
Do not promise that a migration will preserve every position or settle within a fixed number of days. Also keep AI citations separate from routing tests. A correctly mapped page can remain uncited, and an old citation can still point to a route you need to support.
The practical release question is whether someone following yesterday's documentation link can reach today's relevant answer. Build the map around that outcome, test the actual journey, and keep the evidence with the release.
Hey I'm Uriel Bitton. I write about SEO, AEO, GEO, and helping brands get found in AI answers.
Subscribe for practical ways to grow your brand's visibility in search and AI answers.
Explore HoneyWeRank for SEO and AI visibility.
Top comments (0)