Zendesk Knowledge Migration

Context

Alida’s documentation had grown into a collection of five standalone, product-specific help sites resulting in a fragmented user experience. Alida’s support knowledge base was already stored in Zendesk, so migrating the documentation to Zendesk provided a unified location for all product support information, simplifying access for customers and the Alida support team.

Challenge

The migration involved more than 1,500 DITA topics spread across product-specific user guides. These topics needed to be organized as articles in categories and sections in Zendesk with each section mapping to a separate DITA map (.ditamap) file. This content planning exercise and reorganization required a significant investment of work upfront but resulted in a much cleaner organization of the articles in the knowledge base.

Beyond the sheer volume, the project required a simultaneous toolchain transition. We moved from XMetaL Author to Oxygen XML Author, which supported publishing DITA content directly to Zendesk. I established new workflows for validating DITA content before publication, posting review documentation to staging sites, and managing redirects for Zendesk articles.

Approach

Led the migration project end to end. Converted the authoring environment from XMetaL to Oxygen XML Author, reconfiguring DITA maps and output transforms for direct publishing to Zendesk.

Built a set of Python scripts to test the migration in a sandbox environment and then migrate the articles to Zendesk. This included mapping article IDs for cross-references between different Zendesk sections.

Built a set of GitHub Actions–based workflows to support the new pipeline:

• A staging workflow to publish documentation drafts outside of Zendesk for stakeholder review before going live.
• An optional validation workflow that could be run as a step in the staging workflow using Schematron rules to catch structural and content errors in DITA source before publishing. This included simple rules, such as checking to ensure that a topic had a title or that elements weren’t empty, and more complicated rules that verified that required NPS trademark information was included and applied correctly.
• A redirect workflow to manage article URL changes in Zendesk, preventing broken links for existing users. This workflow ran automatically when changes to the redirect CSV were checked in to GitHub.

Outcome

All documentation consolidated into a single Zendesk Knowledge Base along with existing support knowledge base articles. The automated workflows became the standard publishing process going forward, reducing manual steps and catching errors before they reached production.