How to cite this paper

Kimber, Eliot. “Turning a Battleship: Migrating ServiceNow Documentation to Use DITA Keys.” Presented at Balisage: The Markup Conference 2023, Washington, DC, July 31 - August 4, 2023. In Proceedings of Balisage: The Markup Conference 2023. Balisage Series on Markup Technologies, vol. 28 (2023). https://doi.org/10.4242/BalisageVol28.Kimber01.

Balisage: The Markup Conference 2023
July 31 - August 4, 2023

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.

Author's keywords for this paper:
XSLT; XQuery; DITA; Software Engineering; XML; linking