Services / Migration

Migrate from Confluence or Wikis to AsciiDoc and Markdown

I move documentation out of wikis and CMS-style tools such as Confluence, Notion and Quip, and into AsciiDoc or Markdown in Git. I handle both the mass conversion and the critical editing and auditing that go with it, so you end up with a smaller, current set of docs rather than the same old problems in a new format.

Common wiki and CMS documentation issues

  • Years of out-of-date articles make it hard for readers to find or trust what is current.
  • You keep paying to store content that nobody reads.
  • The content is locked into one tool's format, which makes it hard to reuse or move.
  • Docs sit apart from the code, so they aren't updated or reviewed along with the product.

How a migration runs

  • I inventory and audit your existing documentation.
  • We agree what to keep, merge and archive.
  • I mass-convert the content to the target format with Pandoc, then manually review the pages that will be published.
  • I update links as I go, so the new site works for your customers from day one.
  • If public URLs are changing, I work with you on redirects and on letting your customers know.
  • I archive older content outside your live docs, so it is kept without cluttering the site.
  • I set up a CI/CD pipeline for future updates and additions.

Not everything needs the same treatment

A migration doesn't mean every page gets the same care. Older articles that nobody reads may only need bulk conversion and archiving, which is fast and cheap. Customer-facing pages, such as release notes, need careful conversion and checking, because people rely on them being accurate. Sorting content this way during the audit is what keeps a large migration manageable, and puts the effort where it matters.

Example: auditing and migrating docs at Kaptio

At Kaptio, an audit found a daunting collection of out-of-date articles, previously stored in a paid CMS. Using Pandoc to convert a huge number of these articles in bulk, I moved them to our Notion archives, saving us the CMS bill. This process also impressed upon my colleagues the benefits of docs-as-code, as well as showing the advantages of mass conversion and this form of archiving.

The release notes were where I really shined. I set about my own self-driven project with the aim of building a new public-facing site. This site would naturally require an Antora build achieved through a docs-as-code CI/CD pipeline. I converted the release notes to AsciiDoc with Pandoc and updated the links as I went, so the new site was current and usable for customers.

Why migrate?

With docs-as-code, documentation can be versioned to specific releases, so your product and documentation update together. The documentation system also fits into your existing engineering and update processes.

Systems and tools

  • Migrating from: Confluence, Notion, Quip and other CMS-style systems
  • Migrating to: AsciiDoc or Markdown, stored in Git
  • Conversion: Pandoc, plus manual review
  • Publishing: Antora or Docusaurus

Related: Antora and Docusaurus sites · Docs-as-code CI/CD pipelines

Need a migration? Contact me

Email All services