Case studies · illustrative composites

Composite documentation scenarios

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

Composite

Each scenario is assembled from patterns that recur across documentation sets, not from one project.

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 permission 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 we do not publish client names or client work without written permission, and a page of logos is not something we are going to fake to make a sale. What we can do is describe the work exactly: the same audit, structure, build, review gates and handoff that any project is quoted against.

What is real: The work. Content audits and migration maps, information architecture, docs-as-code builds, redirects and link checks, ticket clustering, structuring for retrieval, review gates, author training and handoff. That is the scope of the seven service lines on the services page, run in the order described on the process page.
What is composite: The company, the 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 sets, so that each situation is concrete enough to recognize. They do not describe one organization.
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 work 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 · no client named · no result measured

A SaaS company 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 SaaS company publishes its product docs on a single hosted documentation platform. Authoring is licensed per seat, so the writers, the product manager who knows the API and the support lead who spots the errors all queue behind a handful of seats. The renewal is 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 an export button nobody has pressed yet.
What was wrong: The export produces HTML written by a WYSIWYG editor: inline font and color 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 work 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 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 normalized, vendor callout blocks mapped onto admonitions, code samples lifted out of styled spans, 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 page arrives in the same shape as the first.

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 conversion 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 license.
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 once.

Documentation migration The migration checklist

Illustrative composite · no client named · no result measured

Scenario 02 · Illustrative composite · no client named · no result measured

Documentation scattered across Confluence, 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 Confluence wiki holds process notes and roughly half the product material. A shared drive holds Google Docs, 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 what is left after several teams each solved their own week.
What was wrong: The same procedure exists in several places and the versions disagree, with no way for a reader to tell which one is current. Search only ever covers a fraction of the material, because each tool searches only itself. A customer gets sent a deck that is several releases 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 always somebody else’s problem.

What the work did, phase by phase

Phase 01

One inventory across every surface

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 the competing 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 from Confluence and the drive 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 aging 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 someone’s private drive.
Your onboarding is a person, not a page.

Confluence to Docusaurus migration The Confluence migration guide

Illustrative composite · no client named · no result measured

Scenario 03 · Illustrative composite · no client named · no result measured

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

Already in Git, already Markdown, already free of any license, 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 long ago and has not touched since. There is no vendor, no license 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, dozens of 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: some pages still describe flags that were removed. Several getting-started guides written by different teams are each partly right. And nothing fails when a link breaks, so dead links accumulate invisibly until a customer finds them.

What the work 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 guide and a small set of 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 rotting again.

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 behavior cannot merge while the page describing that behavior 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.

Docusaurus development Review gates in the handbook

Illustrative composite · no client named · no result measured

Scenario 04 · Illustrative composite · no client named · no result measured

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 again and again.

The situation: The documentation is complete enough. It is also organized 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 and closed by hand, over and over.

What the work did, phase by phase

Phase 01

Mine the tickets and the failed searches

A recent stretch of resolved tickets, exported from Zendesk or Zoho Desk, is 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 deep in 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 an occasional cleanup project.
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.

Support tickets to knowledge base The ticket mining method

Illustrative composite · no client named · no result measured

Scenario 05 · Illustrative composite · no client named · no result measured

A support bot answering from docs that contradict themselves#support-bot-answering-from-messy-docs

The assistant is new. The content it retrieves from is not, and it was never written to be read in fragments.

The situation: A SaaS company adds an AI assistant to its help center and support widget. It retrieves from the existing docs and knowledge base: long pages covering several product versions, articles copied between the product docs and the helpdesk, and procedures shown mainly as annotated screenshots. The launch demo goes well, because the demo questions were chosen by the people who wrote the pages.
What was wrong: Real customers ask in their own words, and the retriever pulls whichever chunk matches best: an outdated version of a procedure, half of a table split across two chunks, or a paragraph that only made sense under a heading it was cut away from. The model answers confidently from that fragment. Support now handles the original question plus the correction, and nobody can say which page caused a bad answer, because pages carry no product, version or audience metadata.

What the work did, phase by phase

Phase 01

An audit from the retriever’s point of view

A sample of real customer questions is run against the current content, and each wrong or vague answer is traced back to the chunk it came from. The output is a prioritized list of pages to split, merge, retitle, tag or retire, with the reason written next to each.

Phase 02

One answer per question

Duplicates between the docs and the helpdesk are resolved to one canonical page, and the others are redirected. Version-specific content is separated, so a chunk never mixes two versions of the same procedure.

Phase 03

Structure a machine can follow

Each section is rewritten to stand on its own: a descriptive heading, the answer in the first sentence, tables kept whole, and procedures written as text with screenshots in support rather than as the only source. Frontmatter carries product, version and audience metadata the retriever can filter on.

Phase 04

A review gate for new content

The same rules become part of the authoring templates and the pull request checklist, so new pages arrive ready for retrieval instead of needing another cleanup later.

What the team could do afterwards

A wrong answer can be traced to a specific page and fixed there.
The assistant can filter by product and version instead of guessing which one the customer means.
Each question has one canonical page, so the bot and the human agents give the same answer.
Screenshot-only procedures now have text the retriever can read.
New pages follow the same structure because the template and the review checklist require it.

Signals this is you

Your support bot answers the demo questions well and real customer questions badly.
The same article exists in your docs and in your helpdesk, and the two have drifted apart.
Your pages carry no metadata for product, version or audience.
Key procedures exist only as screenshots.
Nobody can say which page a bad bot answer came from.

AI-ready documentation Why your support bot hallucinates

Illustrative composite · no client named · no result measured

Your docs

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

The five 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 support tickets, an AI assistant or other languages are part of the picture.
The date forcing the question: a renewal, a launch, a rebrand, an audit.

Return

What comes back

A reply within 1 business day.
A read of your docs: what moves as it is, what gets rewritten, what gets retired.
The phase order, and what we need from your team at each review gate.
A written scope and a fixed USD quote before any work starts.

Timing: The timeline depends on page count, the state of the source and how quickly review gates clear, and it is written into the quote. The phase order behind it is on the process page.
Cost: Migrations start at $4,500, and every other line has a published USD price too. See pricing for the tiers and what each one covers.
Scope: Every service line, and where each one stops, is on the services page. If your situation looks like more than one scenario above, that is normal: most teams are living two of them at once.
Privacy: Nothing you send gets published. If a project ever does become a named case study, it is because written permission was given for it, and the page will say so.

The composites end here · the specifics start with your docs

Send the setup you actually have

Describe your platform, your rough page count and the date forcing the question. You get a reply within 1 business day, not a brochure.

Email [email protected]See how a migration runs All services