Skip to main content

After cutover: what outlasts a docs migration

· 7 min read
voix
Documentation studio

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.

This post is about the three things that outlast cutover: ownership, handover and governance. If you want the step-by-step list for the migration itself, that is the documentation migration checklist. This is about what makes the result last.

A migration changes the operating model, not just the platform​

Moving from a hosted editor to docs as code is not a change of tools in the way that switching word processors is. It changes who can publish, how review happens, where history lives, what breaks and who fixes it. In the old platform, many of those questions had implicit answers built into the product: anyone with an account could edit, publishing was a button, and the vendor handled upgrades.

In a docs-as-code setup, every one of those answers becomes a decision your team has to make and keep making. If the migration plan does not make those decisions explicitly, they get made by default, usually by whoever happens to be most frustrated at the time.

Ownership: three kinds, all named​

The word "owner" hides three different jobs, and a healthy docs platform needs a name for each.

Content owners are responsible for whether a section is accurate. They are usually product managers, engineering leads or senior support staff for their area. They do not have to write everything; they have to approve changes and notice when the product moves on without the docs.

The docs owner is responsible for the whole: structure, templates, style, the review queue and the contributor experience. In a small company this might be a single technical writer or a support lead with dedicated time. Without this role, nobody notices when the review queue stalls.

The platform owner is responsible for the machinery: the build, the dependencies, the hosting, the redirect configuration and the CI checks. This is the role most often left empty after a migration, because in the old platform the vendor did it. A static site generator is not a set-and-forget system. Framework upgrades, security advisories and broken CI runners are real, recurring work.

Write these names down in the repository. Content ownership belongs in a CODEOWNERS file, so review requests route themselves. The docs and platform owners belong in the README, with a backup for each. The handbook page on ownership and governance has a template for the whole ownership map.

Handover: what it actually contains​

A handover is not a meeting at the end of the project. It is a set of artifacts and a period of supported practice, and it should be in the migration scope from the first day.

The artifacts we leave with every team:

  • A runbook covering how to build locally, preview a change, publish, roll back, add a redirect and upgrade the framework.
  • A contributor guide that a new support agent can follow to make their first edit without asking anyone, including how to use the Git host's web editor for people who will never touch a terminal.
  • Architecture decisions, each a short note explaining a choice and the alternative that was rejected, so the next person does not undo a decision without knowing why it was made.
  • The redirect map and its test script, in the repository, with instructions for adding rows.
  • A recorded walkthrough of the repository, the pipeline and the review flow.

And the practice: the first real contributions happen with someone pairing. Reading a contributor guide is not the same as having made three pull requests. We schedule paired sessions with each group of contributors during the first weeks after launch, and we keep a 30-day fix window after delivery so problems found in real use get fixed rather than worked around.

Governance: the decisions that stay made​

Governance sounds bureaucratic, and done badly it is. Done well, it is a short list of decisions that do not have to be relitigated every week. The ones that matter most after a migration:

  • Who can add a top-level section, and who approves changes to the navigation. Without this, the old sprawl grows back.
  • How review works: who must approve, how fast, and what happens when a reviewer is away. A review service level of a couple of business days is a reasonable starting point.
  • What the automated checks enforce, and who can change them. The handbook page on review gates covers the checks we typically configure.
  • How content is retired: when a page is removed, where its URL redirects and who decides.
  • How often sections are reviewed for accuracy, and what happens to a page nobody has confirmed in a year.

Keep all of it in the repository, in plain language, and change it through pull requests like everything else.

The first 90 days: failure modes to watch​

Most post-migration problems show up within the first three months. The ones we watch for:

  • The old platform is still editable. Someone makes an urgent fix there, and now there are two sources of truth. Make the old platform read-only at cutover and close it on a published date.
  • The review queue stalls. Pull requests wait for days, contributors give up and ask the docs owner to make changes for them, and the docs owner becomes a bottleneck.
  • Contributors drift back to side channels. Updates arrive as messages and documents instead of pull requests. Usually a sign that the contribution path is too hard for someone.
  • The first framework upgrade is deferred. Then the second one. By the third, the upgrade is a project.
  • Nobody watches the 404 logs. A missed redirect goes unnoticed until a customer reports it.

Each of these is cheap to fix in week three and expensive in month nine.

Measuring health without vanity metrics​

You do not need a dashboard, but a few numbers reviewed monthly tell you whether the platform is healthy: median time from pull request to merge, number of open pull requests older than a week, broken links caught in CI, pages with no confirmed review in the last year, and 404s from old URLs. The trend matters more than the values.

A migration is finished when the new platform is easier to run than the old one, and it stays finished only if someone is responsible for keeping it that way. Our post on docs as code without the cargo cult covers which parts of the pipeline are worth that ongoing effort.

If you want the handover done properly, it is part of every documentation migration we run, and teams that want ongoing help can keep us on a release operations retainer from $900/month. Tell us where your migration stands through the contact page. We reply within 1 business day.