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? Dieser Beitrag zeigt, wie durch intelligente Reuse-Mechanismen die parallele Dokumentation von Standardsoftware und kundenangepasster Software gelingen kann. Die Lösung liegt in Mechanismen, die die mittlerweile etablierte Darwin Information Typing Architecture bereithält, kurz „DITA“.

Dieser Beitrag richtet sich an Leserinnen und Leser, die erste Erfahrungen mit DITA-basierter Dokumentationserstellung haben. Zusätzlich werden wesentliche Begriffe in den beiden Info-Kästen kurz erläutert (Inf. 01 und Inf. 02).

Als Quellcode sehen

Wenn wir Standardsoftware einschließlich ihrer Technischen Dokumentation als eigenständiges Entwicklungsprojekt betrachten, sind die Quellen und Dateien unserer Dokumentation der Quellcode, analog zum Quellcode der Software. Aus dieser Sicht ist unsere Dokumentation wie Software und setzt sich aus Dokumentationsmodulen von wiederverwendbaren Basisressourcen zusammen. Dokumentation wird wie Software entwickelt und idealerweise tun wir das parallel zum Entwicklungszyklus der Software.

Diese neue Sichtweise hat zur Folge, dass sich die Art und Weise ändern muss, wie wir Dokumentation schreiben oder besser gesagt entwickeln. In dem Szenario, das wir in diesem Beitrag zeigen, muss sich die Dokumentationserstellung an die Softwareentwicklungsprozesse anpassen oder zumindest annähern. Damit sich die Dokumentationserstellung sinnvoll in die Softwareentwicklung einbinden lässt, dürfen die redaktionellen Werkzeuge nicht auf proprietäre Datenformate setzen etwa wie Adobe FrameMaker (unstrukturiert), Adobe InDesign oder Microsoft Word. Diese Programme sind deshalb ungeeignet, weil sie nicht jederzeit maschinell ohne komplexe Konverter lesbar sind. Das ist aber in unserem Szenario erforderlich.

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“ (Abb. 01).

Abb. 01 Dokumentationsentwicklung synchron zur Softwareentwicklung. Quelle Markus Wiedenmaier und Regine Ceglarek

Mit einer agilen Denke und einer Tool-Landschaft, die auf etablierte Standards setzt, ist es möglich, die Technische Redaktion und die Entwicklung zusammenzubringen. Entwickler werden dabei als Content-Provider in den Dokumentationsentwicklungsprozess integriert. Mehr noch: Auch externe Konstrukteure, Entwickler und Berater lassen sich in den Dokumentationsprozess einbinden und auf Grundlage einer modularisierten und wiederverwendbaren Basis mit Inhalten für projektspezifische Dokumentation versorgen.

Schauen wir uns aus Sicht der Technischen Redaktion an, mit welchen Konzepten uns der DITA-Standard bei der agilen Dokumentation unterstützt. Außerdem, wie wir Werkzeuge, die in der Softwareentwicklung bereits etabliert sind, für die redaktionelle Arbeit nutzen können.

Mechanismen für flexible Erstellung

Wiederverwendung (Reuse) ist eines der starken Basiskonzepte von DITA. Und genau diese sehr ausgereiften und ausgefeilten Konzepte helfen, projektspezifische Softwaredokumentation umzusetzen.

Beginnen wir mit dem einfachsten Mechanismus: keyref; keydef und keyref sind nichts anderes als Variablenwerte, die wir in der 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 die beiden Variablen in DITA in eigenen und bei Bedarf auch mehreren Dateien (Key-Maps) definiert.

Allein durch das Wechseln des zugrunde liegenden Geltungsbereichs (Key-Space) können die Inhalte der Dokumentation geändert werden. Die Dateien kann man für eine Publikation einer bestimmten Dokumentationsvariante austauschen oder über das Variantenmanagement im Rahmen eines Profiling ein- oder ausblenden (Abb. 02).

Abb. 02 Beispiel für die Variable "Produktname". Quelle Markus Wiedenmaier und Regine Ceglarek.

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. Das 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 das Fragment referenziert oder eingebettet ist.

Ein Verweis für unterschiedliche Inhalte

DITA geht hier einen Schritt weiter: Über die Adressierung mittels 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. Ein Beispiel ist die zentrale Definition von Sicherheitshinweisen und deren Einbindung an den relevanten Stellen im Dokument-/Topic-Kontext.

Der Einsatz von conkeyref hingegen ist schon 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 also durch das Austauschen eines Verweises auf wiederverwendbare Ressourcen andere Inhalte heranziehen, beispielsweise in einem projektspezifischen Kontext. Dazu ein Code-Beispiel:

<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 oder für die Dokumentation unserer Standardsoftware tauschen wir jetzt nur den Verweis auf den Ressourcen-Pool für Screenshots aus. Ohne eine einzige Änderung in den Basisressourcen erhalten wir die für die jeweilige Dokumentation richtigen Screenshots.

In die Dokumentation hinzufügen

Der conref push-Mechanismus ist 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 können. Hierzu wird ein „Reuse-“ oder besser „Injection-Topic“ erstellt, in dem Inhalt über conref referenziert wird. Das Attribut conaction bei der Referenz 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 zum zweiten nach dem referenzierten Inhalt von außen einhängen. Als dritte Möglichkeit können wir über die Aktion pushreplace einen Inhalt durch den projektspezifischen Inhalt komplett ersetzen.

Voraussetzung dafür, dass es auch in komplexeren Projekten funktioniert und möglichst intuitiv verstanden wird, ist die Definition und saubere Vergabe von IDs für den wiederverwendbaren und erweiterten Inhalt.

Die folgenden Abschnitte zeigen zwei Anwendungsfälle für die Reuse-Mechanismen:

• 1. Oberflächentexte und Screenshots
• 2. Variantenmanagement mit Hilfe des Profiling

Anschließend beleuchten wir Vorteile und Möglichkeiten, die sich aus der geänderten und damit moderneren Betrachtungsweise von Dokumentationserstellung parallel zur Softwareentwicklung ergeben. Hier geht es um die Verwaltung der Dokumentationsinhalte, die Publikationsplanung und die Integration von Externen in den Dokumentationsprozess.

Erster Anwendungsfall

Die beschriebenen Mechanismen können je nachdem, wie intensiv man von ihnen Gebrauch macht, komplex sein. Schauen wir uns deshalb ein Beispiel aus der Praxis an. In der Softwaredokumentation werden oft Texte verwendet, die in Software-Oberflächen erscheinen, um einen Bezug zwischen Anleitung und Software herzustellen. Der Umgang mit diesen Texten, vor allem wenn die Dokumentation in mehrere Sprachen übersetzt werden soll, ist nicht immer einfach. Um diesen Prozess sauber aufzusetzen, bedarf es einer Schnittstelle zwischen Entwicklung und Technischer Redaktion.

Ist eine Software state-of-the-art, werden die Texte in externen Ressourcendateien gepflegt, übersetzt und sprachabhängig in die Software eingebunden. Es liegt nahe, aus diesen Ressourcendateien im Build-Prozess der Software Key-Maps zu generieren. Diese werden wie schon beschrieben über die DITA-Reuse-Mechanismen einfach in der Dokumentation referenziert und sind damit immer aktuell und korrekt.

Manche Software-Builds gehen sogar so weit, dass Screenshots automatisiert im Build-Prozess teilweise sprach- und sogar projektspezifisch erzeugt werden. Auch diesen Mechanismus können wir in der Dokumentationserstellung nutzen, um sprach- und projektspezifische Topics zu erstellen, die diese Screenshots referenzieren (s. vorangegangenes Beispiel). Über den conkeyref-Mechanismus können wir die Screen­shots automatisch in unsere verschiedenen Projektdokumentationen einbinden.

Zweiter Anwendungsfall: Varianten

DITA stellt mit Profiling-Mechanismen die Möglichkeit bereit, bei der Ausgabe bestimmte Inhalte auszuschließen und damit eine kundenspezifische Dokumentation zu generieren. Das passiert über Attribute. Die Profiling-Mechanismen werden bei der Publikation über eine so genannte DITA- VAL-Datei gesteuert. In fast allen DITA-definierten Elementen sind Profiling-Auszeichnungen möglich. Sie lassen sich bei Bedarf auch über eine 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 ein- oder ausgeschlossen werden. Ein maximaler Grad an Flexibilität ist erreicht.

Die Dokumentation läuft parallel

In vielen Softwareprojekten wird ein Version-Control-System (VCS) eingesetzt, etwa GIT, Bitbucket oder (noch etwas klassischer) SVN. VCS bieten damit eine flexible, Release-orientierte Verwaltungsmöglichkeit von Quellcode. Nach unserer neuen Denk- und Sichtweise ist Technische Dokumentation genau das, nämlich Quellcode. Deshalb benötigen wir eine Quellcodeverwaltung, und zwar eine, die sich an den Release-Zyklen unserer Software orientiert und es uns ermöglicht, unsere Dokumentation in die unterschiedlichen Entwicklungsstände der Software, die Release-Zwischenstände, zu integrieren.

Wenn wir so vorgehen, haben wir allein durch die Verwaltung in den entsprechenden Entwicklungsständen unsere Dokumentations-Releases parallel zur Software geschaltet. Das ist speziell für unsere Projektdokumentation hilfreich, da kundenspezifische bzw. unternehmensinterne Anpassungen naturgemäß dem aktuellsten Software-Basis-Release hinterherhängen und die Projektdokumentation auch Basisressourcen älterer Softwarereleases verwenden können muss. Über den Einsatz von VCS und die Zuordnung bestimmter Dokumentationsstände zu bestimmten Release-Ständen der Software wird dies möglich.

Die Publikation planen

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, berücksichtigen vor allem im Test-Driven-Development Tests und Validierungen. Mit dem DITA-Open-Toolkit steht ein kostenfreies Open-Source-Werkzeug bereit. Damit können wir die Generierung der verschiedenen Dokumentationsvarianten inklusive der projektspezifischen Ausgaben automatisiert in den Software-Build-Prozess einbinden und dem Arbeitsschritt nachschalten, der uns beispielsweise die aktualisierten Softwaretexte und Screenshots bereitstellt. Auf diese Weise haben wir eine tagesaktuelle und zum Softwarestand passende Dokumentation zur Verfügung, bezogen auf verschiedene Releases und sogar für verschiedene Zwischenstände der Software und der dazugehörigen Dokumentation. Falls diese Zwischenstände einmal benötigt werden.

Der Dokumentations-Build-Prozess kann die Inhalte in Zwischenschritten validieren – sowohl strukturell als auch bei den referenzierten Variablen und sonstigen Reuse-Bestandteilen. Das Ergebnis ist ein Report über festgestellte Fehler oder Probleme im Datenbestand, die bei Bedarf tagesaktuell nachbearbeitet werden können (bevor das Release vor der Tür steht).

Einbinden von Externen

Nachdem wir die Basisressourcen erstellt und freigegeben haben, liefern wir diese aus – idealerweise mit Erstell-Templates, etwa an Dritte in der Entwicklung oder Beratung. Vorausgesetzt, die Technische Redaktion ist nicht selbst für die Erstellung der projektspezifischen Dokumentation verantwortlich. Auf Basis der Templates haben Externe nun die Möglichkeit, die Projektdokumentation zu erstellen, mit der Vorgabe, die Basisressourcen nicht zu verändern.

Im einfachsten Fall passen sie die projektspezifischen Variablen (keydef) 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 und falls nötig durch eigene programmtechnische Erweiterungen, werden nun die Inhalte mittels der erweiterten Wiederverwendungsmechanismen ergänzt oder ersetzt.

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 dem Endkunden eine auf ihn zugeschnittene Technische Dokumentation. Das ist möglich, indem man genau die Inhalte ändert oder ersetzt, die für diesen Kunden nicht oder in anderer Form zutreffen. Beim nächsten Software-Update sind die Beziehungen (zum Beispiel „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 geändert haben.

Und was ist mit Nutzern oder Kunden, die das so nicht wollen? Auch diese Zielgruppe kann man unterstützen, zum Beispiel mit Microsoft Word. Eine Word-Ausgabe ist nur eine andere Form von Content Delivery und kann aus den bestehenden Dokumentations-Ressourcen von DITA generiert werden.

Die hier beschriebene Infrastruktur stellt eine in den Entwicklungsprozess einer Software integrierte Dokumentationslösung dar, basierend auf etablierten Standards und mit bereits vorhandenen Prozessen und Werkzeugen. Spricht etwas dagegen, Kunden, Beratern, Entwicklern und Konstrukteuren Zugang zu dieser Infrastruktur als speziellem Service zu geben, 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 oder auch Verträge anwenden.