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 Darwin Information Typing Architecture und ist ein XML-basiertes Datenmodell zum Erstellen und Veröffentlichen von Textinhalten. Bei DITA-Dateien handelt es sich um reine XML-Textdateien.
In diesem Beitrag werden folgende Themen behandelt:
Warum DITA?
DITA ist ein Industriestandard für die Erstellung und Pflege umfangreicher Dokumentationssätze und ermöglicht die Veröffentlichung von Inhalten auf mehreren Kanälen von einer einzigen Quelle aus. 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-Authoring-Tool Oxygen XML Author. Es bietet eine robuste Authoring-Umgebung mit einer Vielzahl weiterer Funktionen wie Suche, Validierung und XHTML-Transformationen. Daneben gibt es noch weitere Authoring-Tools wie Framemaker, Arbortext und XMetal.
Wie wir Beiträge erstellen und veröffentlichen
Die Autoren verwenden Oxygen XML Author, um Inhalte in den DITA-Dateien zu erstellen und zu aktualisieren. Da DITA die Veröffentlichung auf mehreren Kanäle von einer einzigen Quelle aus ermöglicht, enthalten die DITA-Textdateien kein Styling, sondern nur strukturierte Inhalte. Für den Web-Kanal wird das gesamte Styling durch externe CSS-Stylesheets bereitgestellt, nicht durch DITA. In unserem Fall wird das gesamte Styling durch die Stylesheets in unserem Guide-Design bereitgestellt.
Wenn wir zur Veröffentlichung bereit sind (in der Regel, wenn ein Feature freigegeben oder aktualisiert wird), verwenden wir Oxygen XML Author, um DITA in XHTML umzuwandeln, eine strengere Version von HTML. Anschließend veröffentlichen wir die XHTML-Inhalte im Help Center mithilfe der Help-Center-API.
Ab Version 24 enthält Oxygen XML Editor ein integriertes Transformationsszenario, mit dem DITA-Themen als XHTML veröffentlicht und direkt als Beiträge in ein Zendesk Help Center hochgeladen werden können. Weitere Informationen finden Sie unter DITA Map Publishing in der Hilfe zum Oxygen XML Editor. Ein Video zu diesem Thema finden Sie unter Publishing Content to Zendesk Help Center in der Hilfe zum Oxygen XML Editor.
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 mit Oxygen XML Author in einer Massentransformation umgewandelt. Die Übertragung in das Help Center erfolgte über die Help-Center-API. Auf diese Weise war die Veröffentlichung in wenigen Minuten erledigt.
Wie wir Dateien verwalten
Wir verwalten unsere DITA-Dateien mit GitHub. Vor der Erstellung oder Aktualisierung eines Beitrags legt ein Autor einen Branch in unserem Repository an, nimmt die Änderungen vor und erstellt dann einen Pull Request. Der Pull Request wird von den anderen Autoren im Team geprüft. Auf diese Weise haben die Autoren die Möglichkeit, ihre Arbeit gegenseitig zu kontrollieren.
Wir speichern Bilder in Amazon S3 (Amazon Simple Storage Service), einem skalierbaren Cloud-Speicherdienst von Amazon Web Services (AWS). Alle Bilder in unseren Beiträgen werden von S3 – und nicht vom Help Center aus – in den Browser der Benutzer 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, Portugiesisch (Brasilien), Italienisch und Chinesisch (Vereinfacht) 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 AWS-API aus unserem Amazon S3-Bucket heruntergeladen. Dann verpacken wir die HTML-Dateien und Bilder und übergeben sie unserem Lokalisierungsanbieter. Die übersetzten Beiträge und Bilder werden anschließend wieder per Help-Center- und Amazon AWS-API hochgeladen.