Flexibel dokumentieren mit DITA
Standardsoftware wird mit Standarddokumentation ausgeliefert. Für den konkreten Einsatz beim Kunden wird Software oft kundenspezifisch angepasst. Damit ergibt sich die Aufgabe, die Standarddokumentation um die kundenspezifischen Funktionen zu erweitern. Aus der Standarddokumentation entsteht eine Projektdokumentation.
Wie schafft man es, dass Standarddokumentation und Projektdokumentation auch bei Updates und Weiterentwicklung der Standardfunktionen noch synchron laufen und man nicht zwei Dokumentationsstände parallel pflegen muss?
Umdenken: Dokumentation als 'Quellcode', der wie Software agil entwickelt wird
Lassen Sie uns Standardsoftware einschließlich der Dokumentation als ein eigenständiges Entwicklungsprojekt betrachten.
Dann sind die Quellen und Dateien unserer Dokumentation der Quellcode, analog zum Quellcode unserer Software. Unsere Dokumentation ist in dieser Sichtweise wie Software.
Sie setzt sich aus Dokumentationsmodulen von wiederverwendbaren Basisressourcen zusammen. Dokumentation wird wie Software entwickelt. Idealerweise tun wir das parallel zum Entwicklungszyklus der Software.
Die Änderung dieses Mindsets hat zur Folge, dass sich die Art und Weise ändern muss, wie wir Dokumentation schreiben oder besser gesagt entwickeln.
In dem Szenario, das wir hier skizzieren, muss sich die Dokumentationserstellung an die Softwareentwicklungsprozesse anpassen oder zumindest annähern.
Damit sich die Dokumentationserstellung sinnvoll in die Softwareentwicklung integrieren lässt, dürfen die Tools zur Dokumentationserstellung nicht auf proprietäre Datenformate (wie unstrukturierter FrameMaker, InDesign, Word) setzen.
Diese Formate sind ungeeignet, weil sie nicht jederzeit maschinell ohne komplexe Konverter lesbar sind. Für unser Szenario ist genau das aber notwendig.
Das führt uns zu XML und damit zum mittlerweile etablierten DITA-Standard. Dokumentationserstellung basierend auf DITA kann die eingangs beschriebene Aufgabe leisten, Standarddokumentation und projektspezifische Dokumentation parallel zum Softwareentwicklungsprozess zu 'entwickeln'.
Eine agile Denke und eine Tool-Landschaft, die auf etablierte Standards setzt, sind eine gute Basis, um Teams der Technischen Redaktion und der Entwicklung zusammenzubringen. EntwicklerEntwicklerinnenEntwickler und EntwicklerinnenEntwickler:innen werden als Content-Provider in den Dokumentationsentwicklungsprozess integriert. Mehr noch: Auch externe KonstrukteureKonstrukteurinnenKonstrukteure und KonstrukteurinnenKonstrukteur:innen, EntwicklerEntwicklerinnenEntwickler und EntwicklerinnenEntwickler:innen und BeraterBeraterinnenBerater und BeraterinnenBerater:innen lassen sich so in den Dokumentationsprozess einbinden. Wir können sie auf der Grundlage einer modularisierten und wiederverwendbaren Basis mit Inhalten für projektspezifische Dokumentation versorgen.
Schauen wir uns an, mit welchen Konzepten uns der DITA-Standard bei der agilen Dokumentation unterstützen kann.
Wir gehen der Frage nach: Wie können wir Werkzeuge, die in der Softwareentwicklung bereits etabliert sind, für die redaktionelle Arbeit nutzen?
Reuse-Mechanismen im DITA-Standard für flexible Dokumentationserstellung einsetzen
Wiederverwendung ist eines der starken Basiskonzepte von DITA. Und genau diese sehr ausgereiften und ausgefeilten Konzepte helfen uns, projektspezifische Softwaredokumentation umzusetzen.
Beginnen wir mit dem einfachsten Mechanismen keyref.
keydef und keyref sind nichts anderes als Variablenwerte, die wir in unserer Dokumentation hinterlegen (keydef) und an den entsprechenden Stellen referenzieren (keyref).
Nichts Neues, denn wir kennen die Anwendung dieses Mechanismus aus Word, FrameMaker und anderen Editoren und Systemen.
Allerdings werden diese Variablen in DITA in eigenen und bei Bedarf auch mehreren Dateien (Key-Maps) definiert. Allein durch das Wechseln des zugrundeliegenden Geltungsbereichs, des Key-Space, können die Inhalte der Dokumentation geändert werden. Die Dateien können für eine Publikation einer bestimmten Dokumentationsvariante ausgetauscht oder über das Variantenmanagement im Rahmen eines Profiling ein- oder ausgeblendet werden.
Auch der conref-Mechanismus erschließt sich schnell.
Es können Inhalte aus einem Ressourcen-Pool referenziert und in die Publikation integriert werden.
Adobe FrameMaker zum Beispiel implementiert einen ähnlichen Mechanismus in der unstrukturierten Variante mittels Text-Insets.
Ein Text-Inset ist ein Fragment, das als eigenständige Datei gespeichert ist, und dann als referenzierte Kopie in den Inhalt eingebunden wird.
Ändert man dieses Fragment, ändern sich alle Inhalte, in denen dieses Fragment referenziert oder eingebettet ist.
DITA geht hier noch einen Schritt weiter: Über die Adressierung mit Hilfe von IDs im Ressourcen-Topic kann auch nur ein bestimmter Teil eingebunden werden, beginnend bei einer definierten ID und endend mit einer anderen ID.
Ein einzelnes Topic kann so mehrere Ressourcen enthalten, die an verschiedenen Stellen eingebunden werden.
Praktisches Beispiel hierfür ist die zentrale Definition von Sicherheitshinweisen und deren Einbindung an den relevanten Stellen im Dokument-/Topic-Kontext.
Der Einsatz von conkeyref hingegen ist etwas komplexer.
Dieser Mechanismus kombiniert die beiden Ansätze keyref und conref miteinander.
In der DITA-Map wird eine Ressourcen-Datei als Variable definiert und die ID in diesem Topic zusammen mit dem key referenziert.
Damit lassen sich durch das Austauschen eines Verweises auf wiederverwendbare Ressourcen andere Inhalte heranziehen, die für eine projektspezifische Variante der Dokumentation benötigt werden.
Hier ein kleines Code-Beispiel zur Veranschaulichung:
<keydef keys="project.screenshots" href="screenshots.dita" format="dita"/><keydef keys="project.screenshots" href="screenshots-project-A.dita" format="dita"/>In den Basisressourcen verweisen wir auf den Ressourcen-Pool screenshots.dita, der unsere Screenshots und eventuell einen beschreibenden Teil zu den jeweiligen Dialogen enthält.
Da wir uns im Basis-Pool befinden, können das auch Platzhalter-Grafiken sein. Für die projektspezifische Dokumentation tauschen wir jetzt nur den Verweis auf den Ressourcen-Pool für Screenshots aus (screenshots-project-A.dita).
Ohne eine einzige Änderung in den Basisressourcen erhalten wir die richtigen Screenshots für die jeweilige Dokumentationsvariante.
Der conref push-Mechanismus ist dann das obere Ende der Möglichkeiten.
conref push ermöglicht uns eine Content Injection. Damit ist gemeint, dass bei der Verwendung von Basisressourcen in einem konkreten Projektkontext Inhalte in die Basisdokumentation hinzugefügt (injiziert) werden.
Hierzu wird ein 'Reuse-' oder besser 'Injection-Topic' erstellt, in dem Inhalt über conref aus der Basisdokumentation referenziert wird. Das Attribut conaction bietet uns drei Möglichkeiten, um Inhalt in die Dokumentation zu injizieren. Zum einen können wir über pushbefore und pushafter Inhalt vor den referenzierten oder nach dem referenzierten Inhalt von außen einhängen. Als dritte Möglichkeit können wir über pushreplace einen Inhalt durch den projektspezifischen Inhalt komplett ersetzen.
Voraussetzung dafür, dass das auch in komplexeren Projekten funktioniert und möglichst intuitiv verstanden wird, ist die Definition und saubere Vergabe sowie Benennung von IDs für den wiederverwendbaren und erweiterten Inhalt.
Die folgenden Abschnitte skizzieren zwei Anwendungsfälle für die Reuse-Mechanismen. Das sind Oberflächentexte und Screenshots sowie das Variantenmanagement mit Hilfe des Profiling.
Anschließend beleuchten wir Vorteile und Möglichkeiten, die sich aus der geänderten und wie wir meinen 'modernen' Betrachtungsweise von Dokumentationsentwicklung parallel zur Softwareentwicklung ergeben.
Hier geht es um die Verwaltung der Dokumentationsinhalte, die Publikationsplanung und die Integration von Externen in den Dokumentationsprozess.
Erster Anwendungsfall: Oberflächentexte und Screenshots
In der Softwaredokumentation werden oft Texte verwendet, die in den Software-Oberflächen erscheinen, um einen entsprechenden Bezug zwischen Dokumentation und Software herzustellen.
Der Umgang mit diesen Texten ist nicht immer einfach, vor allem wenn die Dokumentation in mehrere Sprachen übersetzt werden soll.
Um diesen Prozess sauber aufzusetzen, bedarf es einer Schnittstelle zwischen Entwicklung und Technischer Redaktion.
Wenn eine Software state-of-the-art ist, werden die Oberflächentexte in externen Ressourcendateien gepflegt, übersetzt und sprachabhängig in die Software eingebunden.
Da liegt es nahe, aus diesen Ressourcendateien im Build-Prozess der Software Key-Maps zu generieren. Aus diesen Key-Maps können dann die passenden Inhalte in der Dokumentation referenziert werden. Die Dokumentation bleibt damit immer aktuell und korrekt.
Manche Software-Builds gehen sogar so weit, Screenshots automatisiert und teilweise sprachabhängig sowie projektspezifisch zu erzeugen.
Auch diesen Mechanismus können wir in der Dokumentationserstellung nutzen, um sprach- und projektspezifische Topics zu erstellen, die diese Screenshots referenzieren (siehe Quellcodebeispiel oben). Über den conkeyref-Mechanismus können wir die Screenshots automatisch in unsere verschiedenen Projektdokumentationen einbinden.
Zweiter Anwendungsfall: Variantenmanagement
DITA stellt mit Profiling-Mechanismen die Möglichkeit bereit, bei der Ausgabe bestimmte Inhalte auszuschließen.
Damit wird eine kundenspezifische Dokumentation generiert. Das passiert über Attribute. Die Profiling-Mechanismen werden bei der Publikation über eine sogenannte DITA-VAL-Datei gesteuert.
In fast allen DITA-Elementen sind Profiling-Auszeichnungen möglich. Sie lassen sich bei Bedarf auch über Spezialisierung auf die konkreten Bedürfnisse erweitern.
Betrachtet man diese Besonderheit isoliert, dann hilft das bereits, projektspezifische Dokumentation zu generieren.
In Kombination mit den beschriebenen Reuse-Mechanismen vergrößern sich die Möglichkeiten zusätzlich. Denn auch Reuse-Topics oder Key-Maps können über den Profiling-Mechanismus entsprechend ein- oder ausgeschlossen werden. Ein maximaler Grad an Flexibilität ist erreicht.
Integration von Dokumentation in den Softwareentwicklungsprozess: Verwaltung der Inhalte
In vielen Softwareprojekten werden Version-Control-Systeme (VCS) eingesetzt, etwa GIT, Bitbucket oder (noch etwas klassischer) SVN.
VCS bieten damit eine flexible, release-orientierte Verwaltungsmöglichkeit von Quellcode.
Nach unserer neuen Sichtweise ist Technische Dokumentation genau das, nämlich Quellcode.
Deshalb benötigen wir eine Quellcodeverwaltung. Und zwar eine, die sich an den Releasezyklen unserer Software orientiert. Eine Verwaltung, die uns auch ermöglicht, unsere Dokumentation in die unterschiedlichen Entwicklungsstände der Software zu integrieren.
Wenn wir so vorgehen, haben wir allein durch die Verwaltung in den entsprechenden Entwicklungsständen unsere Dokumentationsreleases parallel zur Software geschaltet.
Das ist speziell für unsere Projektdokumentation besonders hilfreich, da kundenspezifische Anpassungen naturgemäß dem aktuellsten Software-Basis-Release hinterherhängen. Projektdokumentation muss daher auch Basisressourcen älterer Softwarereleases verwenden können.
Über den Einsatz von VCS und die Zuordnung bestimmter Dokumentationsstände zu bestimmten Releaseständen der Software wird dies möglich.
Planung der Dokumentationspublikation: daily/nightly builds
Weil wir Dokumentation als Quellcode betrachten, können wir auch den Publikationsprozess wie einen Software-Build-Prozess ansehen. In vielen Szenarien laufen Software-Builds automatisch. Sie berücksichtigen vor allem im Test-Driven-Development Tests und Validierungen.
Mit dem DITA-Open-Toolkit steht ein kostenfreies, als Open-Source-verfügbares Werkzeug bereit.
Damit können wir die Generierung der verschiedenen Dokumentationsvarianten inklusive der projektspezifischen Ausgaben automatisiert in den Software-Build-Prozess integrieren. Wir können so die Dokumentgenerierung dem Arbeitsschritt nachschalten, der uns die aktualisierten Softwaretexte und Screenshots bereitstellt.
Auf diese Weise haben wir tagesaktuelle und zum Softwarestand passende Dokumentation zur Verfügung, bezogen auf verschiedene Releases und sogar, wenn notwendig, für verschiedene Zwischenstände der Software und der zugehörigen Dokumentation.
Der Dokumentations-Build-Prozess kann die Inhalte in Zwischenschritten validieren. Das kann sowohl strukturell als auch hinsichtlich der referenzierten Variablen und sonstiger Reuse-Bestandteile geschehen.
Das Ergebnis ist ein Report über festgestellte Fehler oder Probleme im Datenbestand, die bei Bedarf tagesaktuell nachbearbeitet werden können (bevor das nächste Release vor der Tür steht).
Einbinden von Externen in die Dokumentationserstellung
Nachdem wir die Basisressourcen erstellt und freigegeben haben, liefern wir diese an Dritte aus, zum Beispiel an BeraterBeraterinnenBerater und BeraterinnenBerater:innen oder KonstrukteureKonstrukteurinnenKonstrukteure und KonstrukteurinnenKonstrukteur:innen. Idealerweise geben wir dieser Lieferung Erstell-Templates mit. Auf Basis der Templates haben Externe die Möglichkeit, die Projektdokumentation zu erstellen, mit der Vorgabe, die Basisressourcen nicht zu verändern.
Im einfachsten Fall passen sie die projektspezifischen Variablen (keyref) in den Template-Dateien an und ergänzen im Anhang projektspezifische Details, die zunächst nichts mit der Software selbst zu tun haben.
Bei der Anpassung der Software, sprich bei der Konfiguration oder, falls nötig, durch eigene programmtechnische Erweiterungen, werden nun die Inhalte mittels der erweiterten Wiederverwendungsmechanismen ergänzt oder ersetzt.
Fazit: Dokumentation, die passt
Da Software an sich schon strukturiert ist, lassen sich in konkreten Fällen auch Wege finden, um Informationen direkt aus der Software zu extrahieren und in die Dokumentation zu integrieren.
Einfachstes Beispiel sind hier die Oberflächentexte der Software.
Dieses Vorgehen ist zwar komplex und erfordert eine entsprechende Lernkurve, gerade wenn Dritte ins Spiel kommen.
Die Vorteile dieser Herangehensweise liegen jedoch auf der Hand: Man nutzt die bestehende Standarddokumentation und liefert eine kundenspezifisch zugeschnittene Dokumentation.
Das ist möglich, indem man genau die Inhalte ändert oder ersetzt, die kundenspezifisch abweichen. Beim nächsten Software-Update sind die Beziehungen ( z. B. conref) weiterhin vorhanden.
Die Dokumentation aktualisiert sich im Standardbereich von selbst. Außerdem muss nicht die gesamte Dokumentation neu erstellt werden, sondern nur die Teile, die sich von einem Release zum nächsten tatsächlich geändert haben.
Und was ist mit Unternehmen, die keine xml-Daten als Lieferung akzeptieren, sondern Word-Dokumente erwarten?
Auch diese Zielgruppe lässt sich unterstützen. Eine Word-Ausgabe ist nur eine andere Form des Content Delivery. Sie kann aus den bestehenden DITA-Dokumentations-Ressourcen problemlos generiert werden.
Die hier beschriebene Infrastruktur stellt eine Dokumentationslösung basierend auf etablierten Standards und meist bereits vorhandenen Prozessen und Werkzeugen dar. Diese Lösung ist in den Software-Entwicklungsprozess integriert. Spricht etwas dagegen, Ihre KundenKundinnenKunden und KundinnenKund:innen, BeraterBeraterinnenBerater und BeraterinnenBerater:innen, EntwicklerEntwicklerinnenEntwickler und EntwicklerinnenEntwickler:innen und KonstrukteureKonstrukteurinnenKonstrukteure und KonstrukteurinnenKonstrukteur:innen auf diese Infrastruktur als speziellem Service zugreifen zu lassen und sie in Ihren Prozess zu integrieren und damit an Ihr Unternehmen zu binden?
Was hier für Softwaredokumentation beschrieben wurde, lässt sich leicht auch auf Betriebsanleitungen, Angebote, Verträge und andere Dokumentationsarten übertragen.
Unser Angebot: Konvertierung Ihrer Word-, InDesign-, FrameMaker-Dokumente nach DITA
Wir unterstützen Sie auf Ihrem Weg zu einer Dokumentation, die auf Standards basiert und damit viele Automatisierungsmöglichkeiten eröffnet.
