Process
A documentation migration runs in seven phases: content audit, information architecture, platform implementation, content migration, author enablement, CI/CD delivery and handoff. This page describes each one — what happens, what we need from you, and what exists when it ends — in enough detail to follow the method whether or not you hire voix to run it.
Run in order. Each one ends in something you can open and inspect.
Within two business weeks of the deposit and the required materials arriving.
On full payment you own the deliverables: the repository, the content and the pipeline.
The sequence
A documentation migration has seven phases: audit the existing content, redesign the information architecture, build the open-source 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.
The phases map onto the four things voix sells. Consolidation and information architecture covers phases one and two, platform implementation covers three and four, enablement covers five, and CI/CD delivery covers six. The seventh, handoff, is how every engagement closes. The services page describes each service as a piece of work you can buy on its own.
Phase 01 / Content audit and migration map
Nothing gets migrated until every existing page has a row in a spreadsheet 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 is 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.
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 / Open-source platform build
Docusaurus, in your Git repository, on your hosting, at your domain, standing up before any content lands in it.
The platform is Docusaurus: Markdown and MDX in Git, built to static files. 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.
Nothing in the stack is proprietary and nothing is licensed per seat. Every dependency is open source and every configuration file sits in the repository you own. The migration handbook walks through how the pieces fit together if you want to build it yourself.
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 artefacts 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 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 people from a 404, which is why this phase is not left until last.
Phase 05 / Author and reviewer training
A migration only voix 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 someone in the room.
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. 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 other six decaying. Once publishing is a merge, updating the documentation stops being a project. CI/CD documentation delivery can also be bought on its own if your content is already in Git.
Phase 07 / Ownership, governance and handoff
The engagement 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 get argued about six months 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 next year:
The five interventions package is optional and costs a small extra amount on top of the project fee. It covers five post-launch maintenance interventions for fixes and minor updates, which is worth having in the first months when the awkward questions are still arriving. It is described in full on the pricing 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. voix also retains a copy of the initial delivered project for one year, after which the project lives on your Git account or your own hosting.
Your side of the work
Delivery is measured from the day the deposit and the required materials arrive, so this checklist is the part of the timeline you control completely. Most of it can be gathered before the proposal 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.
Timing
Standard delivery is within two business weeks, measured from the day the deposit and the required materials arrive — not from the first conversation, and not from the day the proposal is signed.
Tell us what platform you are on, roughly how many pages it holds and who owns them. You get back a scope, a phase plan and a quote.