How Ping Identity Migrated from DITA to AsciiDoc
Two teams, two doc systems, one move: ditch DITA for AsciiDoc. Here’s how Ping Identity migrated 48 k pages of documentation.
In September 2023, when Ping Identity merged with ForgeRock, the documentation teams faced a massive task: migrating and merging 48,000 pages from DITA into a unified AsciiDoc infrastructure.
This guide explores key lessons from my interview with Jodie Landes, Senior Director of Technical Documentation at Ping Identity. Want to learn more? Check out the full interview. Plus, I can highly recommend her talk at Write The Docs Portland 2025.
Why AsciiDoc Over DITA?
DITA offers robust content reuse, but it can be overly complex and costly. Ping Identity’s documentation team discovered:
Limited actual reuse: Despite expectations, DITA reuse was minimal.
Costly tooling: DITA tools (Ixiasoft, Fluid Topics) had significant recurring expenses.
"We had issues with Ixiasoft and Fluid Topics. There would just be a huge lag time. And so now we don't have to deal with that anymore."
Conversely, AsciiDoc, particularly through a Docs-as-Code approach, offered:
Faster content creation and publishing.
Lower costs, utilizing open-source tools.
Greater flexibility and future adaptability.
Cost Savings with AsciiDoc
By replacing costly DITA solutions with AsciiDoc, Ping Identity achieved substantial savings. Annual tool licensing costs dropped dramatically from expensive fees to minimal or even free options.
Moreover, publishing speeds improved significantly, moving from slower to faster workflows. These savings allowed Ping Identity to reallocate their budget, enabling them to hire two additional technical writers.
Steps to Migrating from DITA to AsciiDoc
Ping Identity’s migration relied heavily on automation, using custom Python scripts and XSLT.
Content Conversion: Automated transformation using scripts.
Manual Cleanup: Addressed spacing issues, incorrect markup, and extra symbols.
Continuous Improvement: Writers developed scripts to streamline subsequent tasks.
“The ultimate goal through the conversion was to have writers spend as little time as possible having to clean up.”
Common Conversion Challenges
Spacing and Markup Issues: Easily fixable but extensive in volume.
Legacy Link Breakage: Old links presented unexpected hurdles. Ensure a robust link-migration strategy.
Training Writers in AsciiDoc
AsciiDoc’s simplicity facilitated rapid onboarding. Training involved:
A four-day intensive workshop at Ping’s Denver headquarters.
Hands-on exercises with converted content.
Immediate team integration and feedback loops.
Tip: For smooth onboarding, leverage experienced team members as built-in trainers.
“Anyone can pick up AsciiDoc. The real challenge was Git, but learning it adds significant value to writers' skillsets.”
The Human Factor: Managing Resistance
Initially, writers resisted changing familiar workflows. Over time, the simplicity and speed of AsciiDoc, along with ownership in tool customization, significantly reduced resistance.
Initial Resistance: Normal human response.
Reduced Resistance: Proven ease and improved workflows overcame initial skepticism.
“Now writers can publish independently without waiting on third-party approvals.”
Summary
Ultimately, Ping Identity’s successful migration depended on fostering a "possibility mindset," breaking down silos, and rapidly proving the practical value of AsciiDoc.
“Get teams working together on a single project immediately post-merger. This breaks down silos effectively.”
Plus, Jodie shared valuable retrospective advice:
Employ dedicated project management resources early in the project.
Develop a comprehensive link management and migration strategy.
Prepare for legacy documentation pitfalls proactively.
Incorporating AsciiDoc into your documentation strategy offers flexibility, cost efficiency, and improved team productivity. All in all: It's a compelling choice for modern technical documentation.
