Process
A docs-as-code migration runs in seven phases: content audit, information architecture, platform build, conversion and redirects, author training, review gates and publishing, and handoff. This page describes each one by what goes in, what comes out and the review gate that closes it, in enough detail to follow the method whether or not you hire us to run it.
Run in order. Each one ends in something you can open, inspect and approve.
The next phase starts only after you sign off the output of the last one.
A 30-day fix window, then an optional release-ops retainer if you want one.
The sequence
A documentation migration has seven phases: audit the existing content, redesign the information architecture, build the docs-as-code platform, convert the content and map the redirects, train the authors, automate the review and publishing pipeline, then hand over ownership. Each phase depends on the one before it, so they run in order rather than in parallel.
This page follows line 1 of our seven service lines, docs-as-code migrations, because it is the flagship and has the most moving parts. The other lines reuse pieces of the same sequence: ticket mining and AI-ready structuring start with the same audit, localization and release ops run through the same review gates, and docs-site engineering is the build and pipeline phases sold on their own. The services page describes every line and its price.
Phase 01 / Content audit and migration map
Nothing gets migrated until every existing page has a row in the inventory and a decision written next to it.
We pull the current platform into one inventory: one row per page, with its URL, title, section, owner, the date of its last meaningful edit, its traffic if you have analytics, and a decision. The decision is one of four words: keep, merge, rewrite, retire. The export is read as data rather than as a website, so pages that no navigation reaches still show up in the count.
Four things are worth looking for by name:
Retire is a real option and it gets used. A page nobody opens and nobody will own is cheaper to delete and redirect than to carry into a new platform and maintain forever.
Phase 02 / Information architecture
The structure is agreed and signed off before a single page is converted, because moving a page twice costs more than deciding once.
Documentation is separated into content types, and each type gets a template: concept, task, reference, tutorial, troubleshooting, release note. A task page and a reference page are different shapes, and mixing them is the reason pages grow long and stop being findable, by readers and by the retrieval systems behind AI assistants alike.
Then the conventions that keep the structure stable:
Versioning boundaries are decided here too: whether readers need older versions at all, which version is the default, and how far back support goes.
Phase 03 / Docs-as-code platform build
Docusaurus, MkDocs/Zensical or GitBook, in your Git repository, on your hosting, at your domain, standing up before any content lands in it.
The default is Docusaurus: Markdown and MDX in Git, built to static files, extendable with React. MkDocs with Zensical suits teams that already live in Python; GitBook suits teams that want a hosted editor on top of a Git repository. The choice is made in writing, with the trade-offs spelled out, and the Docusaurus, MkDocs and GitBook comparison covers the same ground if you want to decide first.
The repository is yours from the first commit rather than transferred at the end, so there is never a moment where the work lives somewhere you cannot reach. Whichever generator renders it, the content stays in Markdown in that repository, so the choice can be reversed later without another migration.
Phase 04 / Conversion, redirects and QA
The pages move, the vendor markup does not, and every URL you have ever published still resolves to something useful.
Pages become Markdown or MDX. Wrapper markup, inline styles and editor artifacts are dropped rather than translated. Tables and code blocks are rebuilt as real tables and real code blocks. Images are re-exported, renamed to match the page they belong to and referenced by relative path. Front matter is added to every file: title, description, sidebar position, slug.
Then the part that decides whether your readers, and search engines, ever notice the migration happened:
Bookmarks, inbound links from other sites and search results all still point at the old URLs. Redirects are the only thing keeping those readers from a 404, which is why this phase is not left until last. The platform-specific details are in the Confluence to Docusaurus guide and the Zendesk to Docusaurus guide.
Phase 05 / Author and reviewer training
A migration only we can maintain has not finished. Authors publish a real page during training, not a practice one.
Training is a working session rather than a lecture. Each author brings a page that genuinely needs writing and, during the session, creates a branch, writes it in Markdown, previews the rendered result, opens a pull request, takes a review and merges it. The first pull request is the one people remember, so it happens with us on the call.
Writers who have never touched Git get the same session. The workflow is taught through the browser editor first and the command line only for the people who want it.
Phase 06 / Review gates and publishing pipeline
Every pull request builds the site, checks the links and produces a preview URL. Merging publishes. Rolling back is a revert.
The pipeline runs in whatever CI your engineering team already uses, most often GitHub Actions. Documentation gets the same delivery discipline as code because it now lives in the same place as code.
This is the phase that stops the others decaying. Once publishing is a merge, updating the documentation stops being a project. Pipeline work can also be bought on its own as docs-site engineering if your content is already in Git.
Phase 07 / Ownership, governance and handoff
The project ends with named owners, a written governance model and a playbook covering everything you would otherwise have to email us about.
Ownership is recorded in the repository, per area of the documentation tree, so a pull request reaches the person able to judge it. Governance answers the questions that otherwise get argued about later: how a new page is proposed, who approves a change to the navigation, when the terminology list is updated, and how often each section is reviewed for staleness.
The handoff playbook is written for the person who joins your team after we have gone:
Delivery is followed by a 30-day fix window: anything we delivered that does not work as scoped is fixed at no charge. If you want ongoing help after that, the optional release-ops retainer, from $900/month, keeps changelogs, release notes, versioned docs and screenshots moving with every release. It is described on the release notes service page.
Two commercial facts belong in this phase. On full payment you own the final deliverables, while voix keeps the rights to its own pre-existing tools, templates and know-how. And the project has lived in your Git organization and on your hosting since the first commit, so there is nothing to transfer and no voix login to lose.
Your side of the work
The timeline in the quote assumes these arrive when the phases need them, so this checklist is the part of the schedule you control completely. Most of it can be gathered before the quote is even signed.
Everything you send is used only to deliver the work, and access is limited to the people who need it. Nothing about your project is published or named without your written consent. The confidentiality policy sets that out in full, and the documentation migration checklist turns this list into something you can work through before the first call.
Timing
It depends on how many pages move, how messy the source export is, and how quickly your review gates clear. The timeline is written into the fixed quote before work starts, so you know the date before you commit.
Tell us which platform you are on, roughly how many pages it holds and who owns them. You get a reply within 1 business day, then a scope, a phase plan and a fixed USD quote.