Balisage Paper: Turning a Battleship: Migrating ServiceNow Documentation to Use DITA Keys
Eliot Kimber
Senior Product Content Engineer
ServiceNow
Eliot Kimber is a founding member of the W3C XML Working Group, the OASIS Open DITA Technical Committee, a co-author of ISO/IEC 10744:1996, HyTime, and a long-time SGML and XML practitioner in a variety of domains. When not wrangling angle brackets Eliot likes to bake. Eliot holds a black belt in the Japanese martial art Aikido.
Abstract
Describes the analysis, design, planning, and data processing ServiceNow used to migrate all of its DITA-based ServiceNow Platform product documentation from the use of unmanageable direct-URL references for all reuse references and hyperlinks to the use of key-based indirect linking within and among publications. The technical solution uses DITA keys for all links, including use of DITA’s “cross deliverable” linking feature, which enables authoring links from one publication to another (similar to DocBook’s cross-book links but with different implementation challenges). Focuses on the XSLT and XQuery migration process used to perform the migration over a four-day period in the pause between semi-yearly product releases.