Trendige Dokumentation und DITA 1.2

Ende 2010 wurde die Version 1.2 von DITA verabschiedet. Sie bringt eine Reihe von Neuerungen. Aspekte der Zusammenarbeit im Team und vereinfachte Verwaltung stehen im Fokus. Einige Domänen – insbesondere der Bereich E-Learning – wurden spezifisch ausgeprägt. Wie unterstützen diese Erweiterungen die aktuellen Megatrends, mobile Dokumentation und Collaboration?

Single Sourcing – eine gesunde Basis auch für mobile Doku

Die Erstellungsseite steht vor neuen Herausforderungen, denn die neuen Medien und ihre technischen Möglichkeiten entwickeln sich schnell. Sie lösen nicht unbedingt die bestehenden ab, sondern müssen parallel neben den vorhandenen bedient werden. Die Folge dieser Entwicklung ist, dass dieselben Inhalte in immer mehr Medien für unterschiedliche Zwecke, in unterschiedlicher Form und in immer kürzeren Zeiträumen bereitgestellt werden müssen. Hier hat sich das Single-Source-Prinzip bewährt, und die topicorientierte Strukturierung ist die beste Basis für erfolgreiches Single Sourcing. Basierend auf dem topicorientierten Grundprinzip hat DITA auch in der neuen Version die Möglichkeiten für Single Sourcing und Wiederverwendung konsequent erweitert. Dazu gehören folgende Neuerungen:

keys und keyref
glossref
conref push und conref range
coderef

Mehr Freiheit durch indirekte Adressierung über keys und keyref

Eine große Stärke von DITA sind seit jeher die vielseitigen Möglichkeiten, Beziehungen und Links darzustellen. Bisher musste allerdings das Linkziel in der Quelle fest angegeben werden. Daraus entsteht eine große Abhängigkeit. Wenn das Linkziel nicht vorhanden ist, oder die Adresse sich ändert, muss das Quell-Topic nachbearbeitet werden. DITA 1.2 führt indirekte Adressierung ein, um dieses Problem zu beheben. Statt das Linkziel direkt zu adressieren, wird nur eine frei definierbare Bezeichnung (key) für das Linkziel angegeben. Erst in der Map werden den Keys passende Verweisziele zugewiesen.

Abbildung 1: Indirekte Adressierung mit keys und keyref

Variablen mit keys und keyrefs

In DITA 1.2 können mit keys und keyref auch Variablen definiert und verwendet werden, typischerweise zum Beispiel für Produktbezeichnungen und Versionsnummern. In den Topics werden nur die Variablen verwendet. Erst die Map, die die Topics zusammenstellt, legt auch die Werte für die Variablen fest. Damit muss zum einen die Festlegung erst stattfinden, wenn eine Dokumentation produziert wird und zum anderen können aus denselben Topics unterschiedliche Varianten erzeugt werden, indem in den Maps den Variablen unterschiedliche Werte zugewiesen werden.

Vielfältige Möglichkeiten über glossref

Die Möglichkeiten für Begriffserklärungen wurden deutlich erweitert. Da diese Inhaltsart gut bekannt ist, wurden sinnvolle spezielle Elemente festgelegt, um eine spätere Verarbeitung zu vereinfachen und zu standardisieren. So wurde ein neues glossref-Element eingeführt, das die indirekte Adressierung nutzt und dazu dient, von einem Begriff auf seine Definition zu verweisen. Die indirekte Adressierung ermöglicht es, demselben Begriff in unterschiedlichen Kontexten verschiedene Definitionen zuzuordnen. Für die Publikation in einem Online-Medium sind sehr nutzungsfreundliche Darstellungen denkbar, etwa, dass die Definition wie ein Tooltip erscheint, wenn der Begriff angewählt wird.

Flexiblere Wiederverwendung über conref push und conref range

Die bisherigen Möglichkeiten, über conref Inhalte innerhalb von Topics wiederzuverwenden, wurden durch conref push und conref range erheblich erweitert. Jetzt ist es mit conref push möglich, Inhalte in Topics auszutauschen und vor oder hinter definierten Stellen zu ergänzen. Mit conref range können nicht nur einzelne Elemente wie zum Beispiel ein Handlungsschritt (step) aus anderen Topics übernommen werden, sondern auch Bereiche, beispielsweise eine ganze Folge von Schritten.

Nicht-DITA-Texte referenzieren

Ein weiteres interessantes Element der neuen DITA-Version ist coderef. Es referenziert eine externe Datei mit textuellem Inhalt und fügt diesen an der referenzierenden Stelle ein. Auf diese Weise kann zum Beispiel Programmcode in der Dokumentation eingebunden, wiederverwendet und flexibel ausgetauscht werden.

Zusammenarbeit in geregelten Bahnen

Zusammenarbeit (Collaboration) ist ein nicht mehr ganz neuer Trend, hat aber seine volle Blüte noch lange nicht erreicht. Die bisherigen Erfahrungen zeigen, dass es geeigneter Vorgaben bedarf, damit die Zusammenarbeit in geregelten Bahnen verläuft. DITA bietet in der Version 1.2 Neuheiten, die in diesem Zusammenhang eingesetzt werden können.

Mit Constraints kann die Syntax ohne Spezialisierung eingeschränkt werden. Auf diese Weise können Konventionen in einem Projektumfeld für ein Team eindeutiger festgelegt werden. So können optionale Elemente entfernt oder obligatorisch gesetzt und die Reihenfolge von Elementen vorgeben werden.

Eine vielversprechende Möglichkeit, klare Vorgaben zu machen, bieten Subject Schemas. Sie erlauben für ein konkretes Umfeld die Festlegung von spezifischen Attributwerten und Bezeichnungen für Metadaten, ohne in die DTDs eingreifen zu müssen.

Ergänzungen für die Begriffswelt ermöglichen die Definition von Terminologie bis hin zu kompletten Taxonomien. Damit kann die Grundlage für semantische Web-Funktionen geschaffen werden: systematisch, standardisiert und integriert in die Quellinhalte.

Fazit

DITA hat den Trend der Zeit nicht verschlafen. Es eignet sich hervorragend als Quellformat, um auf Autorenseite für schnelle und vielfältige Entwicklungen gerüstet zu sein.

Je mehr DITA genutzt wird, desto mehr wird auch die Nutzungsseite tool-mäßig unterstützt. Die Ausgabe von DITA-Quellen ins EPub-Format ist heute bereits vorhanden, es gibt Wikis auf Drupal-Basis, die DITA als Quellformat nutzen, und es entstehen mehr und mehr Tools, die aus DITA-getaggten Daten Inhalte für die mobile Darbietung automatisch extrahieren.

Referenzen

[1] Bertram, M., Closs, S.: Wie geht Single Sourcing für mobile Endgeräte?, Dok-Magazin, München, Mai/Juni 2011 S.28-32
[2] Closs, S.: Single Source Publishing – Topicorientierte Strukturierung und DITA, 300 Seiten, Verlag entwickler.press, München, 2007
[3] DITA 1.2 Spezifikation, http://docs.oasis-open.org/dita/v1.2/spec/DITA1.2-spec.html, abgerufen 10.9.2011

Vortragsfolien

Vortragspräsentation (PDF)

Jedes Feedback ist willkommen: closs@comet.de