Die gesamte öffentlich zugängliche Produktdokumentation für Zendesk wird in diesem Zendesk Help Center veröffentlicht Während die meisten anderen Teams bei Zendesk Inhalte direkt im Help Center erstellen, erstellt und unterhält das Dokumentationsteam die Produktdokumentation offline in DITA-Quelldateien. DITA steht für Document Information Typing Architecture und ist ein XML-basiertes Datenmodell zum Erstellen und Veröffentlichen von Textinhalten.
In diesem Beitrag werden folgende Themen behandelt:
Warum DITA?
DITA ist ein Industriestandard für die Erstellung und Unterhaltung umfangreicher Dokumentationssätze. Das Problem, das dieser Standard lösen soll, beschreibt Jacquie Samuels auf techwhirl.com wie folgt:
Inhalte in Word, E-Mail, PowerPoint, WordPress, HTML, InDesign, FrameMaker oder anderen Formaten zu schreiben ist so ähnlich, wie sie in Steintafeln zu ritzen. Ihr Inhalt steckt praktisch in diesem Format fest und ist unflexibel wie ein Felsbrocken. Solcher „Dumb Content“ lässt sich nur schwer wiederverwenden oder umfunktionieren und ist deshalb ineffizient und teuer.Mithilfe von DITA lassen sich Inhalte so schreiben und speichern, dass Sie wie andere Assets verwaltet werden können. Die verwendete XML-Sprache (eXtensible Markup Language) sorgt dafür, dass Ihre Inhalte intelligent, vielseitig, verwaltbar und portabel sind.
DITA-Inhalte können beispielsweise (mit vollem Branding) als PDF, HTML, RTF, PowerPoint und in mobilen Formaten veröffentlicht werden, ohne einzelne Teile durch Kopieren und Einfügen zu übertragen.
(Quelle: What Is DITA? auf TechWhirl)
Neben der Trennung von Inhalt und Format bietet DITA dem Zendesk-Dokumentationsteam noch eine Reihe weiterer Vorteile:
- Inhalte müssen streng strukturiert werden. DITA-Dateien werden im XML-Format geschrieben. Wenn ihre Struktur ungültig ist, können sie mit dem Tool nicht verarbeitet werden.
- Inhalte können mühelos verschoben werden. Wir brauchen lediglich einen Themenknoten an eine andere Position in der Struktur zu verschieben.
- Inhalte können durch Importieren von Textteilen in mehrere Artikel wiederverwendet werden.
- Wir veröffentlichen selten im PDF-Format, doch wenn, verwenden wir DITA-Quelldateien.
Hierbei nutzen wir das DITA-Autorentool „Oxygen XML Author“. Es bietet eine robuste Autorenumgebung mit einer Vielzahl weiterer Funktionen wie Dateisuche, Dateivergleich, Änderungsverfolgung und HTML-Transformationen. Daneben gibt es noch weitere Autorentools wie Framemaker, Arbortext und XMetal, um nur einige zu nennen.
Wie wir Beiträge im Help Center veröffentlichen
Wir verwenden Author, um Inhalte in DITA-Quelldateien zu erstellen oder zu aktualisieren. Für die Veröffentlichung (die in der Regel zum Zeitpunkt der Einführung oder Aktualisierung der betreffenden Produktfunktion erfolgt) wandeln wir die DITA- in HTML-Dateien um und kopieren den HTML-Quellcode in Guide von Hand in den Artikelcode. Dieses Verfahren ist zwar nicht sehr elegant, dafür aber um so einfacher.
Gelegentlich kommt es vor, dass wir in kurzer Zeit eine große Anzahl von Beiträgen aktualisieren müssen. Als Zendesk beispielsweise seine Preisinformationen und Branding-Infos vereinfachte, mussten Hunderte von aktualisierten Beiträgen bis 8 Uhr morgens an einem bestimmten Tag veröffentlicht werden.Die DITA-Quelldateien wurden in den Wochen vor der Umstellung von den Autoren aktualisiert und dann in einer Massentransformation per Zendesk-API umgewandelt und in das Help Center hochgeladen. Auf diese Weise war die Veröffentlichung selbst in wenigen Minuten erledigt.
Für die Massenveröffentlichung verwendeten wir ein allgemein verfügbares Open-Source-Tool auf Github (siehe https://github.com/chucknado/zpu). Die dazugehörige Bedienungsanleitung finden Sie in der Readme-Datei unter https://github.com/chucknado/zpu/blob/master/README.md.
Wie wir Dateien verwalten
Wir speichern die DITA-Dateien auf einem Google Team Drive, das sie automatisch mit den Computern der einzelnen Autoren synchronisiert. Auf diese Weise haben die Autoren jederzeit die aktuellen Dokumentversionen zur Hand. Wenn ein Autor Änderungen an einem Beitrag speichert, werden diese per Team Drive-Synchronisation direkt an die Computer der anderen Autoren übertragen. Zudem speichert Team Drive alle Änderungen der letzten 30 Tage. Auch hier ist das Ziel ein möglichst einfaches Verfahren.
Bilder speichern wir ebenfalls auf dem Google Team Drive, laden sie aber zur Veröffentlichung auf einen Amazon S3-Dateiserver hoch. Alle Bilder in unseren Beiträgen werden von S3 und nicht aus dem Help Center in ihren Browser heruntergeladen Der Amazon S3-Service vereinfacht die Verwaltung der Bilder.
Wie wir lokalisierte Artikel veröffentlichen
Die Standardsprache des Help Centers ist Englisch. Außerdem wird die Produktdokumentation auf Deutsch, Spanisch, Französisch, Japanisch, Koreanisch und Portugiesisch (Brasilien) veröffentlicht.
Wenn Inhalte übersetzt werden sollen, laden wir die entsprechenden englischsprachigen Beiträge über die Help-Center-API herunter und schreiben sie in HTML-Dateien. Die Bilder zu den Beiträgen werden über die Amazon-API aus unserem Amazon S3-Bucket heruntergeladen. Dann packen wir die Dateien und übergeben sie an unseren Lokalisierungsanbieter. Die übersetzten Beiträge und Bilder werden anschließend wieder per Help-Center- und Amazon-API hochgeladen.
Der API-Client, mit dem wir die Übergabe von Dateien managen, heißt ZLO (Zendesk Localization Tools) und wurde intern vom Dokumentationsteam entwickelt. Der ZLO-Client ist Open Source und auf Github unter https://github.com/chucknado/zlo verfügbar. Weitere Einzelheiten finden Sie in der Dokumentation auf Github.