Case studies

Documentation migration scenarios

Every scenario on this page is an illustrative composite. voix does not publish a client name or client work without written consent, so instead of a case study with a logo on it, here is what these engagements look like: the estate at the start, what is wrong with it, the migration phase by phase, and what the team can do afterwards. No company is named. No number is reported.

Composite

Each scenario is assembled from patterns that recur across documentation estates, not from one engagement.

No metrics

Nothing here claims a measured result. Outcomes are described as things the team can newly do.

Confidentiality

Client work and client names stay private unless written consent says otherwise. That is the confidentiality policy, not a formality.

Read this first

Why are these case studies composites instead of named clients?#why-these-are-composites

Because voix does not publish client names or client work without written consent, and a page of logos is not something this studio is going to fake to make a sale. What it can do is describe the work exactly: the same audit, migration map, architecture, implementation, delivery pipeline and handoff that any engagement is quoted against.

What is real: The work. Content audit and migration map, information architecture redesign, Docusaurus implementation, versioning, CI/CD publishing, search and navigation, authoring standards, contributor training, governance, QA and redirects, launch and handoff. That is the delivery scope set out on the services page, run in the order described on the process page.
What is composite: The company, the page counts, the specific mix of tools and the order in which the complaints arrived. Those are stitched together from patterns that show up again and again in documentation estates, so that the situation is concrete enough to recognise. They do not describe one organisation.
What is absent: Names, logos, quotes and numbers. There is no testimonial on this page and no percentage, because voix has no published client result to report and an unsourced statistic is decoration, not evidence.
How to read them: Each scenario runs in the same order: the situation, what was wrong with it, the migration phase by phase, what the team could do afterwards, and a short list of signals that the scenario is describing you. Read the signals first if you are in a hurry.

Scenario 01 · illustrative composite

A scaleup leaving a paid documentation platform#scaleup-leaving-a-paid-platform

One hosted platform, authoring priced per seat, and an export button that produces markup nobody can maintain.

The situation: A B2B product company publishes a few hundred pages on a single hosted documentation platform. Authoring is licensed per seat, so the two writers, the product manager who knows the API and the support lead who spots the errors are all queued behind three seats. The renewal is annual and priced against headcount, so the bill grows every time the company hires. All content sits in the vendor database, and the only way out is the export button that nobody has pressed yet.
What was wrong: The export produces HTML written by a WYSIWYG editor: inline font and colour styles on every heading, wrapper divs carrying generated block ids, span tags around single words, and tables assembled out of nested divs. Images come back as URLs pointing at the vendor CDN, so the export stops rendering on the day the contract ends. None of it is under version control, which means no diff, no history, no blame and no rollback. The only record of who changed a page is somebody remembering that they said they would.

What the migration did, phase by phase

Phase 01

Audit and migration map

Every published URL is inventoried with its traffic, its last-edited date and an owner, then marked move, merge, rewrite or retire. The output is a table in which each source URL has either a destination path or a written reason it is not moving. Nothing is converted before that table exists, because a migration without a map is just a re-publish of the same mess on cheaper hosting.

Phase 02

A conversion pipeline, not a copy-paste

A script turns the export into Markdown: inline styles and wrapper divs stripped, heading levels normalised, vendor callout blocks mapped onto admonitions, code samples lifted out of styled span soup, and CDN image URLs rewritten to local paths with the assets pulled down alongside. It is a pipeline rather than a one-off because the vendor keeps taking edits while the migration runs, so the whole conversion is re-run against a fresh export at cutover.

Phase 03

Information architecture and the Docusaurus build

Navigation is redesigned around what readers are trying to do rather than around the vendor category tree, versioning is set up to match how the product actually releases, and every page gets real frontmatter: title, description, sidebar position. Recurring page types get templates, so the next hundred pages arrive in the same shape as the first hundred.

Phase 04

Redirects, checks and cutover

Every old URL gets a redirect to its new path, link checking and builds run in CI, the documentation domain is pointed at the new hosting, and the seats are dropped at renewal rather than abandoned mid-term. The handoff includes the conversion scripts themselves, so the team can re-run the migration on anything that surfaces later without calling anyone.

What the team could do afterwards

Anyone with repository access can fix a typo. An edit costs a pull request, not a licence.
Every change has an author, a diff, a reviewer and a one-command revert.
A broken link fails the build instead of reaching a customer.
Documentation deploys from the same CI the product uses, on the day the change is written.
The annual conversation moves from a per-seat renewal quote to a hosting bill the team controls.
The content is Markdown in a repository the company owns, so the next platform decision is a choice rather than an escape.

Signals this is you

Your renewal quote goes up when you hire.
Fewer people can edit the documentation than have opinions about it.
Nobody has run the export yet to see what actually comes out.
Your documentation lives on the vendor domain, or on a subdomain you do not fully control.
Someone has said “we will move off it after the next release” more than twice.

Illustrative composite · no client named · no result measured

Scenario 02 · illustrative composite

Documentation scattered across a wiki, a drive, a helpdesk and a README#docs-scattered-across-tools

Four surfaces, four search boxes, four sets of editing rules, and no single source of truth for anything.

The situation: Documentation grew wherever it was convenient. The internal wiki holds process notes and roughly half the product material. A shared drive holds PDFs and slide decks that sales attaches to emails. The support helpdesk carries a knowledge base written by agents answering the same tickets. The main repository has a README that engineers actually trust, because they wrote it and it sits next to the code. Nobody chose this arrangement. It is the residue of four teams each solving their own week.
What was wrong: The same procedure exists three times and the three versions disagree, with no way for a reader to tell which one is current. Search only ever covers a quarter of the material, because each tool searches only itself. A customer gets sent a deck that is a year behind the helpdesk article. New hires are told to ask in Slack, because nobody can point at a canonical page. And because no topic has an owner, every stale version is simultaneously somebody else’s problem.

What the migration did, phase by phase

Phase 01

One inventory across all four surfaces

Every page, article, deck and document is listed in a single table with its owner, its last edit, its audience and a duplicate-group id. Grouping the duplicates comes before anything is written, because the real work here is not moving files, it is deciding which of three answers is the answer.

Phase 02

Adjudication with named owners

For each duplicate group, one version becomes the source and the others are marked for redirect or deletion. That is a short series of decisions taken by people empowered to take them, not a writing task, and each decision is recorded in the same table so it survives the meeting. Topics that no team will own get an owner here, or they get retired here.

Phase 03

Split by audience, then rebuild the architecture

Customer-facing material moves into a public Docusaurus site; internal process stays internal in a separate build. Navigation is designed around the tasks readers arrive with rather than around the org chart that produced the original folders, and each page type gets a template so the next contributor does not invent a new shape.

Phase 04

Close the old doors

Helpdesk articles are replaced with a short stub pointing at the canonical page, or redirected outright where the tool allows it. The drive folder is archived read-only with a pointer at the top. The README shrinks to the parts that genuinely belong beside the code, plus a link out. Then redirects, link checks and search configuration, so old bookmarks still land somewhere real.

What the team could do afterwards

There is one URL to send a customer, and one place to change what it says.
Every topic has a named owner recorded in a file the whole team can read.
One search box covers the entire customer-facing set.
Sales can send a link that stays current instead of attaching a PDF that starts ageing the moment it is exported.
Onboarding can point at a page instead of at a person.
When two answers conflict, there is a defined way to decide which one wins.

Signals this is you

You cannot answer “where do our docs live” in one sentence.
The same how-to exists in the wiki and in the helpdesk, and the two disagree.
Support agents write knowledge base articles because the product documentation did not cover it.
Something load-bearing exists only in a document sitting in one person’s private drive.
Your onboarding is a person, not a page.

Illustrative composite · no client named · no result measured

Scenario 03 · illustrative composite

Engineering-owned Markdown that quietly drifted#engineering-owned-docs-that-drifted

Already in Git, already Markdown, already free of any licence — and still failing readers, because nothing kept it honest.

The situation: The documentation is Markdown in the same repository as the product, published by a static site generator an engineer wired up two years ago and has not touched since. There is no vendor, no licence and no export problem. Everything is versioned, everything is diffable, and on paper this team has already done the migration everyone else is asking for.
What was wrong: There is no information architecture. The sidebar is the folder listing in alphabetical order, twenty top-level entries deep, with a misc directory at the bottom where pages go to die. Frontmatter is inconsistent, so titles and descriptions in search results are unusable. Documentation is not part of code review, so features ship and their pages do not: several pages still describe flags that were removed. There are three getting-started guides written by three teams, each of them partly right. And nothing fails when a link breaks, so the dead links accumulate invisibly until a customer finds them.

What the migration did, phase by phase

Phase 01

A drift audit the Git history writes for you

Last-touched dates come straight out of the Git log, then get cross-referenced against release notes and the current API surface. Every page ends up classified as current, stale but salvageable, wrong, or delete. The dates make the argument, which turns a political conversation about whose pages are worst into a data exercise anyone can check.

Phase 02

Information architecture and a page-type taxonomy

A task-based hierarchy replaces the folder listing, driven by an explicit sidebar file rather than alphabetical ordering, with one canonical getting-started and four page types: concept, how-to, reference, troubleshooting. Each type gets a template, so new pages have an obvious home. That is the part that stops the structure re-rotting six months later.

Phase 03

Review gates that run in CI

Documentation changes are required in the same pull request as the change that needs them, enforced with code ownership on the docs path. Link checking, frontmatter validation and a prose style check run on every pull request, and a broken anchor fails the build rather than printing a warning nobody reads.

Phase 04

Ownership and a review cadence

Each top-level area is assigned to an owning team in a file in the repository, with a documented review interval. A last-reviewed date in frontmatter is surfaced on the page itself, so a reader can judge the age of what they are reading without opening the Git history to work it out.

What the team could do afterwards

A stale page is visible as a stale page, to the reader and to the owner.
A pull request that changes behaviour cannot merge while the page describing that behaviour still says the old thing.
New pages start from a template with correct frontmatter, so search results become readable again.
The sidebar reflects what readers are trying to do, and it keeps doing that when someone adds a folder.
Broken links fail in continuous integration rather than in front of a customer.
There is one getting-started guide, and everyone knows which one it is.

Signals this is you

Your sidebar is your folder structure.
You have more than one getting-started page.
The documentation is in the repository but not in code review.
Someone can name the page they know is wrong, and it is still published.
Nothing breaks when a link breaks.

Illustrative composite · no client named · no result measured

Scenario 04 · illustrative composite

A support-heavy product whose documentation nobody can find#support-heavy-product

The pages exist and are broadly accurate. Customers still cannot reach them, so support answers the same questions every week.

The situation: The documentation is complete enough. It is also organised the way the product is built: by module, by service name, by the internal noun the team uses in stand-up. Customers search with the words for their problem, not the words for the architecture. So the answer is on the site, the person who needs it opens a ticket instead, and an agent types the explanation out again. Support has quietly become the search interface.
What was wrong: Page titles are internal nouns, so the vocabulary never matches the query. There is almost no troubleshooting content, because troubleshooting knowledge lives in ticket replies and in a folder of canned responses that is better than the published site. The error strings the product prints appear nowhere in the documentation, so pasting the exact message into search returns nothing at all. And there is no route from a ticket back into the docs, so the same gap gets rediscovered every month and closed by hand every time.

What the migration did, phase by phase

Phase 01

Mine the tickets and the failed searches

Three months of ticket subjects are clustered by intent, and the on-site search queries that returned no useful result are pulled alongside them. That produces a ranked list of the questions customers actually ask, in the words they actually use. Nothing has to be invented: the demand is already written down, it has simply never been read as a documentation backlog.

Phase 02

Answer-shaped pages

For the top clusters, pages are written whose title is the question and whose first paragraph is the answer, with the detail underneath for the reader who needs it. A troubleshooting set is keyed to the literal strings the product emits, so pasting an error message into search lands on the page about that error rather than on nothing.

Phase 03

Search and navigation in the reader vocabulary

Pages are retitled into task language, with descriptions and keyword aliases so the internal nouns still resolve for the people who use them. Search is configured and weighted, and the highest-demand questions are placed where a stuck reader is already looking rather than three levels into the tree.

Phase 04

A loop from ticket back to page

Support tags a ticket as a documentation gap, the tag opens an issue in the docs repository, and an owner triages that queue on a set cadence. Support macros link to the page instead of restating it, which makes every reply a live check that the page is still correct.

What the team could do afterwards

An agent answers with a link plus a sentence of context, instead of retyping an explanation.
A customer who pastes an error message into search lands on the page about that error.
Documentation improves as a by-product of support running, rather than in a project every two years.
The team can see which questions still have no page, because the tagging says so.
New agents learn from the same pages customers read, so the two stop diverging.
Product can see, in one queue, where the product is confusing and not only where the docs are thin.

Signals this is you

Support keeps a folder of canned replies that is better than your published documentation.
Your most-visited page is the documentation index, because nobody can get anywhere from it.
You cannot search your own documentation for an error message your own product prints.
Nobody owns the question “what did customers ask us last month” on the documentation side.
Your page titles are your internal names for things.

Illustrative composite · no client named · no result measured

Your estate

What your migration would look like#what-your-migration-would-look-like

The four scenarios above are composites. Yours does not have to be. Send the setup you actually have and you get back a specific read of it rather than a generic one.

Send

What to send

The platform you publish on today, and whether you can produce a full export from it.
Roughly how many pages are published, and your honest guess at how many are worth keeping.
Where content lives: one tool, or a wiki plus a drive plus a helpdesk plus a README.
Whether the documentation is public or gated, versioned, and whether it is translated.
The date forcing the question: a renewal, a launch, a rebrand, an audit.

Return

What comes back

A read of the estate: what moves as it is, what gets rewritten, what gets retired.
A migration map from your current URLs to their destinations, with redirects accounted for.
The phase order, and what voix needs from your team at each phase.
A quote, scoped by documentation volume and implementation complexity.
A written proposal fixing scope, timeline and fees before any work starts.

Timing: Standard delivery runs within two business weeks of the deposit and the materials voix needs. The phase order behind that number is set out on the process page.
Cost: A migration is a one-time project fee, quoted per estate. There is no subscription, no per-seat fee and no recurring platform licence — see pricing for what the fee covers and what the optional add-ons are.
Scope: The four services, and where each one stops, are on the services page. If your situation looks like more than one scenario above, that is normal: most estates are two of them at once.
Privacy: Nothing you send gets published. If an engagement ever does become a named case study, it is because written consent was given for it, and it will say so on the page.

The scenarios above end here · the specifics start with your export

Send the setup you actually have

Describe your platform, your rough page count and the date forcing the question. You get a migration map back, not a brochure.

Email [email protected]See how an engagement runs What voix does