A knowledge base migration is more than exporting articles and importing them into new help center software. Use this reusable checklist to inventory content, map metadata, preserve URLs, test permissions, protect search quality, and validate the new experience before and after launch.
Overview
A documentation migration can affect customers, support agents, employees, developers, and search engines at the same time. The safest approach is to treat it as a controlled content and access project rather than a one-time platform transfer. Your goal is not simply to move every article. Your goal is to move the right content, preserve useful paths, improve findability, and retire material deliberately.
Before choosing an import method, define the migration boundary. Record which collections, languages, audiences, file attachments, videos, code samples, and restricted articles are included. Decide whether the project covers a customer-facing help center, an internal knowledge base, developer documentation, or several properties at once. Each may use different navigation, permissions, URL rules, and review owners.
Keep a working inventory in a spreadsheet or database. Useful columns include:
- Current URL and proposed destination URL
- Article title, content type, collection, language, and owner
- Audience and permission group
- Status: keep, revise, merge, archive, or redirect
- Last reviewed date and next review date
- Page views, search visits, support references, or other available usage signals
- Embedded images, downloads, videos, code blocks, tables, and external links
- Redirect status, migration status, and post-launch validation result
Use the inventory to make editorial decisions before the transfer. A new platform is not a reason to carry duplicate, obsolete, or ownerless content forward. For broader planning, compare this process with the knowledge base creation workflow and the content audit checklist.
Checklist by scenario
For a customer help center migration
- Export all public articles, categories, collections, labels, authors, images, downloads, and language variants.
- List the highest-value customer tasks, such as setup, billing, account access, troubleshooting, and cancellation.
- Identify articles linked from product screens, automated emails, chat replies, onboarding sequences, and support macros.
- Map each old category and article to a destination collection. Avoid recreating navigation that users already find confusing.
- Preserve article intent even when the new URL structure changes. Create one tested redirect for every retained public URL.
- Check that embedded media, downloadable files, anchor links, and expandable sections survive the import.
For an internal knowledge base or employee wiki
- Classify content by audience, department, location, employment status, or other access requirement.
- Audit groups and roles before importing. Match the new platform’s permissions to actual business needs instead of copying outdated access rules blindly.
- Review sensitive material, including HR procedures, security instructions, customer data, and operational credentials. Remove secrets and unnecessary personal information before migration.
- Confirm that search results do not expose restricted article titles, snippets, attachments, or linked files to unauthorized users.
- Assign a named owner and review date to every critical SOP. A useful starting point is this internal knowledge base template.
For developer documentation or API reference content
- Separate conceptual guides, tutorials, reference pages, release notes, examples, and generated API content in the inventory.
- Record version paths and decide which versions remain published, which redirect, and which become clearly labeled archives.
- Test code formatting, syntax highlighting, tabs, request examples, response examples, parameter tables, and copy buttons.
- Verify links between guides and API references, especially links that include version identifiers or page anchors.
- Confirm that the publishing workflow still supports review and updates. Use the API documentation checklist to review clarity after the transfer.
For a platform consolidation or rebrand
- Create a complete old-to-new URL mapping before changing the domain, subdomain, folder structure, or article slugs.
- Decide which overlapping articles become the canonical version and redirect the rest.
- Update brand references, product names, screenshots, contact routes, legal links, and embedded forms.
- Coordinate the cutover with website, product, support, analytics, and engineering owners.
What to double-check
URL and redirect mapping
Build a redirect table with at least the old URL, new URL, redirect type supported by the platform, test status, and owner. Redirect exact equivalents where possible. If an article is merged, send the old URL to the most relevant surviving page rather than to a generic homepage. If no useful replacement exists, document the decision and handle the old path deliberately.
Test redirects in a staging environment if the platform supports it, then test again after launch. Check direct visits, trailing-slash variations where relevant, encoded characters, article anchors, and links from older content. Look for redirect chains and loops. Update important internal links so visitors do not rely on redirects for normal navigation.
Metadata and search
Map titles, descriptions, labels, categories, breadcrumbs, canonical settings, language markers, and search exclusions. Import rules often do not match field names between systems, so inspect samples rather than assuming a successful upload means a complete migration.
Test the new search experience using real questions, product names, error messages, abbreviations, and misspellings. Confirm that relevant articles appear, titles are understandable, and restricted content is handled correctly. Record a small set of baseline searches before migration so you can compare results afterward. Review the related guide on knowledge base metrics for a practical measurement framework.
Permissions and localization
Test access as an administrator, an ordinary customer or employee, a restricted user, and an unauthenticated visitor when those roles apply. Check both page access and asset access. An article can appear protected while a downloadable file or image remains reachable through an old direct URL.
For multilingual content, map language codes, translated slugs, fallback behavior, navigation labels, and hreflang or equivalent settings where applicable. Confirm what happens when a translation is missing and ensure users are not sent to an unrelated language without a clear path back.
Content rendering
Review a representative sample of short articles, long guides, troubleshooting pages, FAQs, tables, code-heavy pages, and media-rich pages. Check headings, lists, links, images, captions, callouts, tables, forms, and mobile layout. Pay particular attention to content copied from rich-text editors, where formatting can create empty paragraphs, broken lists, or unsafe inline markup.
Common mistakes
- Starting with the export: Exporting before defining scope creates duplicate files, missing owners, and unclear decisions. Freeze the inventory first.
- Assuming slugs will remain stable: New platforms often generate different paths. Capture every public URL and create a tested mapping.
- Copying permissions without review: Old groups may contain former teams or overly broad access. Reconcile access with current responsibilities.
- Checking only the homepage: A polished landing page can hide broken article links, missing attachments, failed search results, and inaccessible restricted content.
- Moving outdated content unchanged: Migration is an appropriate point to merge duplicates, rewrite confusing instructions, and retire unsupported workflows.
- Ignoring operational links: Support macros, product prompts, emails, bookmarks, analytics events, and internal SOPs may still point to old URLs.
- Launching without a rollback plan: Keep the old system available in a controlled state for the agreed validation period, and document who can pause or reverse the cutover.
When to revisit
Revisit this migration checklist before every major platform, domain, navigation, authentication, or permissions change. It is also useful before seasonal planning cycles, when support volume or product usage changes, and whenever workflows or documentation tools change.
Use a staged review schedule after launch. Immediately check redirects, access, search, rendering, and critical customer journeys. During the first review period, inspect support tickets, failed searches, page errors, and feedback from agents or employees. At the next documentation review, compare usage and search signals with your baseline, then prioritize rewrites, new articles, redirects, or permission corrections.
Keep the inventory as a living record rather than a disposable migration file. Mark each issue with an owner, priority, evidence, and due date. A migration is complete only when readers can find the right information, authorized users can reach it, unauthorized users cannot, and the team has a maintainable process for updating it. For future projects, the step-by-step help center migration plan can serve as a companion reference.