Im September 2023, als Ping Identity mit ForgeRock fusionierte, standen die Dokumentationsteams vor einer gewaltigen Aufgabe: Sie mussten 48.000 Seiten aus DITA in eine einheitliche AsciiDoc-Infrastruktur migrieren und zusammenführen.

Dieser Leitfaden zeigt zentrale Erkenntnisse aus meinem Interview mit Jodie Landes, Senior Director of Technical Documentation bei Ping Identity. Möchten Sie mehr erfahren? Lesen Sie das vollständige Interview. Außerdem kann ich ihren Vortrag bei Write The Docs Portland 2025 sehr empfehlen.

Warum AsciiDoc statt DITA?

DITA bietet robuste Wiederverwendung von Inhalten, kann jedoch übermäßig komplex und teuer sein. Ping Identity’s Dokumentationsteam stellte fest:

  • Begrenzte tatsächliche Wiederverwendung: Entgegen den Erwartungen war die DITA-Wiederverwendung minimal.
  • Hohe Tool-Kosten: DITA-Tools (Ixiasoft, Fluid Topics) verursachten erhebliche laufende Kosten.

„Wir hatten Probleme mit Ixiasoft und Fluid Topics. Es gab einfach eine riesige Verzögerung. Und jetzt müssen wir uns damit nicht mehr auseinandersetzen.“

Im Gegensatz dazu bot AsciiDoc, insbesondere durch einen Docs-as-Code-Ansatz:

  • Schnellere Inhaltserstellung und -veröffentlichung.
  • Geringere Kosten durch Nutzung von Open-Source-Tools.
  • Größere Flexibilität und künftige Anpassungsfähigkeit.

Kostenersparnis mit AsciiDoc

Durch den Ersatz teurer DITA-Lösungen durch AsciiDoc erzielte Ping Identity erhebliche Einsparungen. Die jährlichen Lizenzkosten für Tools sanken drastisch von hohen Gebühren auf minimale oder sogar kostenlose Optionen.

Darüber hinaus verbesserten sich die Veröffentlichungsgeschwindigkeiten erheblich, indem langsamere durch schnellere Arbeitsabläufe ersetzt wurden. Diese Einsparungen ermöglichten es Ping Identity, ihr Budget umzuschichten und zwei zusätzliche technische Redakteure einzustellen.

Schritte zur Migration von DITA zu AsciiDoc

Die Migration bei Ping Identity basierte stark auf Automatisierung mithilfe benutzerdefinierter Python-Skripte und XSLT.

  1. Inhaltskonvertierung: Automatisierte Transformation mithilfe von Skripten.
  2. Manuelle Nachbearbeitung: Behebung von Abstandsproblemen, fehlerhaftem Markup und zusätzlichen Symbolen.
  3. Kontinuierliche Verbesserung: Autoren entwickelten Skripte, um nachfolgende Aufgaben zu vereinfachen.

„Das ultimative Ziel der Konvertierung war, dass die Autoren so wenig Zeit wie möglich für Nacharbeiten aufwenden müssen.“

Häufige Herausforderungen bei der Konvertierung

  • Abstands- und Markup-Probleme: Leicht behebbar, aber umfangreich in der Anzahl.
  • Defekte Legacy-Links: Alte Links stellten unerwartete Hürden dar. Stellen Sie eine robuste Link-Migrationsstrategie sicher.

Schulung der Autoren in AsciiDoc

Durch die Einfachheit von AsciiDoc war ein schnelles Onboarding möglich. Die Schulung umfasste:

  • Einen viertägigen Intensivworkshop in der Zentrale von Ping in Denver.
  • Praktische Übungen mit konvertiertem Inhalt.
  • Sofortige Teamintegration und Feedbackschleifen.

Tipp: Für ein reibungsloses Onboarding nutzen Sie erfahrene Teammitglieder als interne Trainer.

„Jeder kann AsciiDoc erlernen. Die eigentliche Herausforderung war Git, aber das Erlernen davon bereichert das Skillset der Autoren erheblich.“

Der menschliche Faktor: Umgang mit Widerständen

Anfangs leisteten die Autoren Widerstand gegen Veränderungen bekannter Arbeitsabläufe. Im Laufe der Zeit reduzierten sich die Widerstände durch die Einfachheit und Geschwindigkeit von AsciiDoc sowie durch die Mitgestaltungsmöglichkeit bei der Tool-Anpassung deutlich.

  • Anfänglicher Widerstand: Natürliche menschliche Reaktion.
  • Abgebauter Widerstand: Nachgewiesene Einfachheit und verbesserte Arbeitsabläufe überwanden die anfängliche Skepsis.

„Jetzt können Autoren unabhängig veröffentlichen, ohne auf Genehmigungen Dritter warten zu müssen.“

Zusammenfassung

Letztendlich basierte der erfolgreiche Migrationsprozess von Ping Identity darauf, eine „Possibility Mindset“ zu fördern, Silos aufzubrechen und den praktischen Wert von AsciiDoc schnell unter Beweis zu stellen.

„Bringen Sie Teams unmittelbar nach der Fusion gemeinsam an einem Projekt arbeiten. Das baut Silos effektiv ab.“

Außerdem teilte Jodie wertvolle rückblickende Ratschläge:

  • Setzen Sie frühzeitig dedizierte Projektmanagement-Ressourcen ein.
  • Entwickeln Sie eine umfassende Strategie für Link-Management und Migration.
  • Bereiten Sie sich proaktiv auf Fallstricke bei Legacy-Dokumentationen vor.

Die Einbindung von AsciiDoc in Ihre Dokumentationsstrategie bietet Flexibilität, Kosteneffizienz und eine verbesserte Teamproduktivität. Alles in allem: Es ist eine überzeugende Wahl für moderne technische Dokumentationen.