8 posts tagged with "Docs Migration"

If your documentation runs on Material for MkDocs, nothing broke when the project entered maintenance mode, and nothing will break on the day support ends. What changes is who carries the risk. Every Python upgrade, dependency advisory and browser change after that date lands on your team, with no upstream fix coming. That makes this a planning decision, not an emergency, and the right time to make it is while the maintainers are still shipping security fixes.

A Zendesk help center that has been live for a few years usually ranks for a long tail of how-to queries nobody on the team tracks. Moving it to Docusaurus keeps that traffic only if every old article URL answers with a permanent redirect to its new home on the day you switch. How you do that depends on one question most teams have not asked yet: who controls the domain the help center is served from?

Moving a Confluence space to Docusaurus is mostly a conversion problem with three traps in it: macros that have no Markdown equivalent, a page tree that does not map cleanly to folders, and URLs that carry page IDs your redirects have to honor. This guide covers each step in the order we do it, with the commands and config we actually use.

This is the checklist we work from when a SaaS team moves its documentation off Zendesk, Confluence, Word or Google Docs and onto a docs-as-code stack such as Docusaurus, MkDocs or GitBook. It is ordered by phase, every item is something you can verify, and each phase ends with a gate: if the gate is not met, the next phase waits.

Content conversion is the visible part of a migration and the part that rarely fails. The part that fails is the URL layer: every bookmark, support macro, in-product help button, partner page and search result that points at the old docs. A redirect map keeps those working, and it is usually built last, in a hurry, by whoever is still awake.

Every migration proposal contains the phrase "content audit", and almost nobody says what comes out of one. It is not a reading exercise, and it is not a quality score out of ten. It is a classification pass that ends with one decision per page, a count next to each decision, and a named person who agreed to it.

A documentation migration has a launch date, and most of the planning points at it. Content is converted, redirects are tested, the new site goes live, and everyone relaxes. Then, over the following months, something quieter happens: pull requests wait a week for review, one team goes back to editing the old wiki, a dependency upgrade gets postponed twice, and the new platform slowly becomes as hard to run as the one it replaced. Migrations rarely fail at cutover. They fail in the handover nobody scoped.

Documentation lock-in is almost never visible when you sign up. The editor is pleasant, the hosting is included, search works. You find out what lock-in costs on the day you try to leave: when the export turns out to be a folder of HTML with vendor markup, the URLs belong to someone else's domain, and three years of review history stays behind. The subscription fee is what you pay to stay. The exit cost is what you pay to go, and it is the number worth knowing before you need it.