Charakteristika¶

Aus Ersteller-Sicht besteht eine DITA-konforme Dokumentation aus einer losen Vielzahl von Schritt-für-Schritt Anleitungen, Glossar-Einträgen und Referenz-Dokumenten. Diese Standard Topic-Typen werden je nach Aufgabenstellung und Zielgruppe zu einer Dokumentation zusammengestellt. Die Vielzahl dieser Topic-XML-Dateien stellt hohe Anforderungen an eine geeignetete Dateiverwaltung und könnte im Idealfall mit einem Content Management System (CMS) wie z.B. Archiv/TYPO3 oder einer Versionsverwaltung wie z.B. [Archiv/CVS:CVS] oder Subversion umgesetzt werden. Die Erstellung, Transformation und Verwaltung der DITA Dateien würden in diesem Idealfall kompakt innerhalb eines CMS implementiert sein.

Die Zielgruppe dagegen sieht die inhaltlich zusammengestellte Dokumentation in den meisten Fällen in einer hierarchischen Ordnung abhängig von den unterschiedlichsten Ausgabeformaten wie z.B. PDF und HTML.

Die kleinste Informationseinheit der DITA Specifikation ist ein Topic. Von seiner Definition her ist ein Topic ein autonomer Sachverhalt, welcher je nach Kontext in einem Dokumentationsgebilde angeordnet wird. Vergleiche mit einer Informationsflocke (flake) drängen sich in diesem Zusammenhang auf. Im DITA Standard werden drei Grundtypen von Sachverhalten angeboten, welche in einer technischen Dokumentation immer wieder vorkommen:

• Tasks: Schritt-für-Schritt Anleitungen.

• Concept: für Hintergrundinformationen.

• Reference: für die Aufführung von Kommandos und anderen standardisierten Informationen.

A topic is a unit of information with a title and some form of content, short enough to be specific to a single subject or answer a single question, but long enough to make sense on its own and be authored as a unit. Quelle: OASIS Architectural Specification 1_1 Chapter 3 DITA markup 🇬🇧

Es gibt somit keine Beschränkung für den Umfang eines DITA Topics. Allerdings sollte bei Topic's ab drei Sätzen immer die Frage auftauchen, ob im diesem Fall aus Versehen zwei Topics miteinander vermischt werden. Zwei miteinander vermischte Topics lassen sich schwerer wiederverwenden.

Jedes Topic steht für sich allein und ist ohne zusätzliche Kontextinformation verständlich. Für die Erstellung der zielgruppenorientierten Dokumentation werden Verweise zu den Topics mittels sogenannter DITA-Maps listenartig angeordnet.

Sollten diese Grundtypen den eigenen Anforderungen nicht genügen, können aufbauend auf den Grundtypen durch eine sogenannte Specialisation eigene Topic-Typen erstellt werden (fortgeschritten).

Generell gibt es in einer topic-orientierten Auflistung keine Wertungen. Listeneinträge an erster Stelle sind damit nicht wichtiger als Listeneinträge an letzter Stelle. Diese Gleichbehandlung lässt sich sehr gut mit dem Mindmapping trainieren und sollte vor der Arbeit (u.a.) mit DITA persönlich verinnerlicht sein.

Einstieg¶

Zum Einlesen empfiehlt sich die Lektüre der ditaref-book.chm Dokumentation. Diese CHM-Datei befindet sich nach dem Entpacken des DITA Open Tool Kit im Pfad ~/doc/ditaref-book.chm Die CHM-Dateien lassen sich unter Linux mit verschiedenen CHM Betrachtern öffnen.

Als Einstieg in die DITA-konforme Dokumentation sollte ein bestens bekanntes Thema gewählt werden. In der Softwaredokumentation empfiehlt sich eine Dokumentation über den "Datei > Drucken..." oder den "Bearbeiten → ..." Dialog zu erstellen. Diese Menü-Einträge tauchen in den meisten Softwarelösungen auf und sind damit sehr gut wiederverwendbar.

Als Vorarbeit für die Erstellung einer umfangreichen DITA konformen Dokumentation wird die Zielgruppe bestimmt. Dafür bieten sich sogenannte Use Cases an. In einer Art Brainstorming werden relevante Schlüsselwörter gesammelt bzw. später hinzugefügt. Hierbei ist Mut zur Lücke das Vorgehensprinzip. Danach werden diese zielgruppenrelevanten Schlüsselwörter entsprechend den Topic-Typ-Vorgaben (z.B. task, concept usw.) beschrieben und mit Metadaten z.B. Computeranfänger, Profi, KDE, GNOME, Xfce, usw. versehen. Zur Verwaltung einer Vielzahl von Topics sind die Topics bzw. deren Metadaten zwingend von einer Desktopsuche (Software) zu indexieren. Um die Verwaltung der Dita-Dateien zu verbessern, empfiehlt es sich einheitliche Metadaten vorzuschreiben.

Nun wird für die betreffende Zielgruppe eine DITA-Map angelegt. Über die Indexliste der Metadaten werden die passenden Topics herausgefiltert. Diese sind dann dem voraussichtlichen Lesefluß des Zielpublikum entsprechend listenartig anzuordnen.

Um eine universelle Wiederverwendung von Topics zu gewährleisten, ist bei der Zusammenstellung auf eine strikte Trennung von Wie- (=Schritt-für-Schritt) und Was- (=Hintergrundinformationen) Informationen zu achten. Diese strikte Vorgehensweise ermöglicht die Zusammenstellung von zielgruppengerechter Dokumentation.

Während der Herausbildung der inhaltlichen Struktur werden mit einem Transformationstool (z.B. dem DITA Open Tool Kit) automatisch visuelle Layoutinformationen hinzugefügt. Beispiele für Ausgabeformate sind z.B. PDF oder HTML.

Eine ausführliche Beschreibung ist im OASIS DITA DOC Archiv 🇬🇧 zu finden.

Im wiki.ubuntuusers.de werden verschiedene Includes Makros verwendet um häufig wiederkehrende Hinweise und Warnungen wiederzuverwenden. Die Include-Funktion bietet ähnliche Funktionalität wie das Dita content inclusion (conref) Attribut. Weitere Informationen sind unter DITA Version 1.1 Architectural Specification S. 40 unten ca. 3MB PDF ⮷ und DITA Version 1.1 Language Specification S. 478 unten ca. 13MB PDF ⮷ zu finden.

⚓︎

Grundinstallation¶

Die folgende Anleitung zum Einrichten einer DITA Publishing Umgebung sollte ähnlich auch unter anderen Linux-Distributionen funktionieren. S.a. Andere Distributionen Folgende Pakete müssen (unter Ubuntu 6.06 LTS Dapper Drake) installiert sein. Die Bezeichnungen für die Java 5 bzw. Java 1.5 Pakete neuerer Ubuntu-Versionen können davon abweichen ^[1]:

• sun-java5-jre (multiverse ^[2])

• sun-java5-jdk (multiverse)

• CHM-Betrachter (Auswahl)

  • gnochm für Gnome optimiert

  • chmsee für Gnome optimiert

  • kchmviewer für KDE optimiert

  • xchm (universe) JavaScript-Elemente wie Mouseover-Informationen werden nicht unterstützt.

  • fbreader allgemeiner e-book Reader

Alternativ kann auch die Sun Java Runtime Environment - JRE Version 6 bzw. 1.6 und aktueller verwendet werden. Ähnlich das Sun Java Development Kit - JDK.

optional:

• bzr-gtk (universe) Vorgefertigte Pakete sind unter Ubuntu seit 6.10 Edgy verfügbar. S.a. Downloads Für Dapper muss wahrscheinlich das Olive 🇬🇧 -Plugin in Bazaar eingebunden werden. Umfangreiche Dokumentation kann hier 🇬🇧 gefunden werden.

• Kate Unter einem Standard Gnome Ubuntu wird die komplette KDE Umgebung nachinstalliert.

Der XMLmind Editor funktioniert ausschließlich mit der offiziellen Version von Sun Java Microsystem. Mit dem GNU Compiler for Java 🇩🇪 Version 1.4 kommt es zu Problemen beim Drag & Drop zwischen dem Editor und dem Dateimanager.

Um herauszufinden, welche Java Runtime Environment (JRE) momentan aktiviert ist, wird im Terminal ^[6] eingegeben:

java -version 

Sollte jetzt als Ausgabe erscheinen:

java version "1.4.2"
gij (GNU libgcj) version 4.1.0 (Ubuntu 4.1.0-1ubuntu8)

Copyright (C) 2006 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

... sind einige Einstellungen zu korrigieren. Unter Ubuntu 6.06 LTS Dapper Drake sind die Java Bibliotheken im Pfad /usr/lib/jvm/ abgelegt. Bei der Installation des Sun Java Runtime Environment wird meist ein Menü-Eintrag zu einem sogenannten Sun Java Plugin Control Panel angelegt. Dort finden sich über den Reiter Java Application Runtime Settings auch Informationen über die aktuellen Dateipfade der Java Bibliotheken. Sollte dort ein Ordner

• /java-1.4.2-gcj-4.1-1.4.2.0/ aufgeführt sein,

sind die Pakete

• gij-4.1 und

• java-gcj-compat zu entfernen. ^[1]

Dabei ist zu beachten, dass nach dem Entfernen dieser Pakete eventuell andere Java-Anwendungen nicht mehr funktionieren werden. Insbesondere eine bestehende Eclipse-Version aus den Ubuntu-Softwarequellen wird in diesem Fall nicht mehr funktionieren. Eventuell ist eine Ubuntu-Installation in einer Virtuellen Maschine zu überdenken. Dazu sind aber mindestens 1 GB Arbeitsspeicher und ca. 10 GB zusätzlicher Festplattenspeicher notwendig (s.a. VirtualBox und Archiv/VMware).

Sollte als Ausgabe erscheinen:

java version "1.5.0_06"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_06-b05)
Java HotSpot(TM) Client VM (build 1.5.0_06-b05, mixed mode, sharing)

wird der XMLmindEditor von Pixware ordnungsgemäß funktionieren.

Editoren¶

Vom Prinzip her lässt sich jeder XML-Editor verwenden. Die DITA DTDs 🇩🇪 lassen sich hier 🇬🇧 herunterladen und müssen dann in den jeweiligen XML-Editor eingebunden werden.

XML-Editoren besitzen sehr strikte Vorgaben bei der Eingabe von neuen Elementen des jeweiligen XML-Dialektes (z.B. DITA, DocBook etc). Diese Vorgaben wurden von Spezialisten auf dem jeweiligen Gebiet erarbeitet. Sollte ein Element an einer bestimmten Stelle im DITA-Dokument im Editor nicht verfügbar sein, wird dies einen Grund haben. So hat es z.B. unter DITA keinen Sinn nach einem stepresult ein abstract Element einzufügen. Sollte der Cursor nach dem stepresult gesetzt sein, ist das abstract Element nicht verfügbar. Die Qualitätssicherung findet damit zu ca. 80 % während der Eingabe statt bzw. wird gemäß den Vorgaben in der DTD validiert.

DITA Transformation¶

Es ist auch möglich das DITA Open Tool Kit mit einer graphischen Oberfläche durch das Eclipse "Run > As" Menü auszuführen. Genauere Hinweise für die Einrichtung können im Ditainfocenter.com 🇬🇧 gefunden werden.

⚓︎

./startcmd.sh 

ant samples.web -f build_demo.xml 

ant all -f build_demo.xml 

ant -f build_demo.xml 

Buildfile: build_demo.xml

BUILD SUCCESSFUL
Total time: X minutes X seconds

java -jar lib/dost.jar /i:/Dateipfad/zur/hello_world.ditamap /transtype:xhtml 

java -jar lib/dost.jar /i:/home/dita-account/00-personal-dita-publishing-environment/ditamaps-and-topic-subdirectories/beginners-tutorial.ditamap /transtype:xhtml 

./startcmd.sh 

ant -f ~/00-personal-dita-publishing-environment/transformation-starter-scripts/dita2xhtml-starter-script.xml 

...
ant -f ~/00-personal-dita-publishing-environment/transformation-starter-scripts/dita2xhtml-starter-script.xml
bash

Unable to locate tools.jar. Expected to find it in /usr/lib/jvm/java-1.5.0-sun-1.5.0.06/lib/tools.jar

Verwaltung der DITA Dateien (Topics)¶

Zur Verwaltung der DITA Dateien empfiehlt sich der Einsatz eines speziellen Desktop-Suchprogrammes. Dieses Suchprogramm muss allerdings auch in der Lage sein, einige Tausend und mehr XML-Text-Dateien komplett durchsuchen zu können. Die Suche bzw. Filterung nach Dateinamen ist für die Verwaltung von DITA-Dateien nicht ausreichend.

Literaturempfehlungen¶

Links¶