staging.inyokaproject.org

via DuckDuckGo

Darwin Information Typing Architecture

Hinweis:

Dieser Artikel enthält ausschließlich Hintergrund (=Was?) Informationen zum dita Thema. Um einen Lost-in-Hyperspace Effekt zu vermeiden, wurden die meisten weiterführenden Hyperlinks dita-like unter der Überschrift Links am Ende dieses Wikibeitrags angelegt. Ausnahmen sind Links zu Download Archiven die den direkten Download einer Datei auslösen und nicht die Gefahr eines Lost-in-Hyperspace provozieren.

Inhaltsverzeichnis
  1. Charakteristika
    1. Minimalismus
  2. Einarbeitung in das DITA Fachgebiet
  3. Editoren
    1. DITA Open Tool Kit
      1. Dokumentationen produzieren
      2. Plugins
  4. Verwaltung der DITA Dateien (Topics)
  5. Literaturempfehlungen
    1. Einsteiger
    2. Fortgeschritten
  6. Links
    1. DITA Einstieg
    2. Fortgeschritten

./dita-logo-f-uude.jpg

Die Darwin Information Typing Architecture - DITA ist ein XML-Dialekt mit einer strikten Trennung von Inhalt und visuellen Layout Informationen. Vorrangiges Ziel der Darwin Information Typing Architecture ist die 1:1 Wiederverwendung (Reuse) von Mini-Dokumentationen in verschiedenen Kontexten. Damit kann die Qualitätssicherung von Wiki-Artikeln schon während der Erstellung durchgeführt werden.

Ein typisches Anwendungsgebiet wären z.B. die Beschreibung identischer Funktionen im Mozilla Firefox Browser, Thunderbird E-Mail und Sunbird Kalender. Außerdem läßt sich beobachten, daß viele Funktionen über die unterschiedlichen Versionen (z.B. von Firefox Version 1.5 zu Firefox Version 2) bestehen bleiben. Die Beschreibung/Dokumentation für diese identischen Funktionen werden in sogenannten Quelldateien einmal erstellt und über eine Verweis- bzw. Referenzmethode (ditamap's) in die jeweilige Softwaredokumentation (z.B. von Firefox 1.5 und Firefox 2) eingebunden. Dieses mikromodulare Bausteinsystem ist für den Endanwender nahezu unsichtbar und erscheint für die Zielgruppe aus einem einheitlichen Guss. Dadurch wird chaotisches 'Kopieren & Einfügen' vermieden und das Original läßt sich eindeutig bestimmen bzw. warten. DITA eignet sich natürlich auch für die Erstellung von Dokumentationen für die unterschiedlichsten Zielgruppen wie z.B. Anfänger/Fortgeschritten/Entwickler. Auch hier werden identische Dokumentationsbestandteile 1:1 wiederverwendet.

Anwendungsfall bzw. Use Case Screencast für Dita Authoring 🇬🇧 - Ab 4:03 min wird die Wiederverwendung von Informationsfragmenten demonstriert. Das wiederverwendete Informationsfragment ist ab 4:40 min grau eingefärbt.

Pixware XMLmind screencast (siehe screenshoots, flashdemos) 🇬🇧 - In diesem Screencast wird der Eingabezwang bzw. rote Faden für den Inhaltsersteller demonstriert. Der eingegebene Inhalt wird dabei automatisch mit semantischen XML tags versehen. An der Stelle wo sich der Cursor links im Text der technischen Dokumentation befindet ist nur die Bearbeitung bzw. Hinzufügen von inhaltlichen Elementen erlaubt welche im oberen rechten Feld sichtbar sind.

Bezogen auf die Wiki-Dokumentation von Ubuntuusers.de würden eigentlich alle erwähnten Inhaltselemente welche im Wiki Syntax mit 'muß' und 'immer' markiert sind in eine DTD oder XML-Schema gehören. Während der Erstellung eines Wiki-Artikels wird von einer Software-Lösung automatisch das Verwenden von bestimmten Wiki-Elementen (also diesen uu.de 'muß' und 'immer'-Elementen) erzwungen. Dadurch macht eine Software-Lösung automatisch darauf aufmerksam, daß der neu erstellte Wiki-Artikel nicht den Ubuntuusers.de Wiki-Richtlinien entspricht.

InyokaEdit

Die Wiki Textbausteine folgen im weitesten Sinne dem 'Dokumentations-Paradigma der Wiederverwendung von Inhaltselementen'. DITA-XML umfaßt aber den kompletten Dokumentationsprozeß.

DITA baut auf den bewährten Erfahrungen im Bereich des Datenbank-Design, der Objektorientierten Programmierung und der Technischen Dokumentation auf. Software der Technischen Dokumentation werden als Help Authoring Tools (HAT) bezeichnet. Als Berufsbezeichnung für Dita AnwenderInnen hat sich der Begriff "Information Architect" etabliert. Vor der Einarbeitung in das DITA Konzept sollten Strukturierungsfähigkeiten mit hierarisch orientierten Techniken wie z.B. dem Mindmapping trainiert werden. DITA konforme Strukturierung erfordert einen nicht unerheblichen Einarbeitungsaufwand. DITA ist ähnlich dem XML basierten OpenOffice ODF Office-Formaten ein OASIS Standard.

Ein weiteres Anwendungsgebiet von DITA konformer Dokumentation könnte die Erstellung von Storybooks und Sprecher-Scripten für Screencasts sein. Nach einer Umwandlung dieser dita konformen Sprecher Scripte in pdf besteht auch die Möglichkeit mittels der Read Aloud Text-to-Speech Funktion des Adobe Acrobat Readers eine Soundausgabe auszulösen. Diese Soundausgabe läßt sich über die Soundkarte (Line-In) aufnehmen und dann mit Audacity in eine mp3 Datei umwandeln. Während des Abspielens der dita konformen Audio Anweisungen auf einem portablen Audio Player wird dann parallel mit einem Screencasting Programm der eigentliche Screencast erstellt. Der erstellte Screencast ist somit indirekt dita konform bzw. stimmt genau mit den anderen Transformationen wie z.B. der *.chm Version überein. Auch die Wiederverwendung von einzelnen Video Frame Sequenzen könnte ein Anwendungsgebiet von Dita sein. Für die Einbindung von Video Frame Sequenzen (z.B. *.flv, *.avi etc.) von Screencast- und Utility-Filmen bietet sich das "object" dita Tag an.

Parallel zu der Erstellung einer technischen Dokumentation sollten auch die Anforderungen eines Translation Memory Systems (TMS) beachtet werden. Dadurch ist es möglich erstellte Dokumentationen (teil-)automatisiert in andere Zielsprachen zu übersetzen.

Charakteristika

Minimalismus

Beschreibung des Minimalismus aus der Sichtweise der Organisation für die Verbesserung von strukturierten Informationsstandards (OASIS):

Topic orientiertes Authoring von konzeptueller Information und Arbeitsaufgaben basiert auf dem sogenannten Minimalismus. Diese informative Modellierungstechnik wurde als erstes von John Carroll vorgestellt. Dieser minimalistische Ansatz in der Informationsmodellierung konzentriert sich darauf die kleinste Menge an Arbeitsanweisungen zu bestimmen, welche den erfolgreichen Abschluß einer Arbeitsaufgabe zum Ergebnis hat oder grundlegendes Wissen zu einem Konzept bereitstellt.

Anwender einer technischen Dokumentation haben Ziele. Diese Ziele möchten sie so schnell wie möglich erreichen. Das Lesen einer technischen Dokumentation ist für die entspechende Zielgruppe keine unterhaltsame Angelegenheit wie z.B. das Lesen eines Romanes. Die Verwendung von Übergangstext/Transitional Text zementiert die Inhalte einer Dokumentation und erschwert eine universelle Wiederverwendung. Die Zielgruppe einer technischen Dokumentation möchte etwas lernen oder eine Arbeitsaufgabe vollenden.

Einige der Kernprinzipien des Minimalismus sind:

  • Unterstützung von Aktionen. Anwender sollen durch das Sammeln von Erfahrungen agieren. Sie sollten nicht daran gehindert werden ihre Ziele zu erreichen.

  • Es sollten Arbeitsanweisungen (Schritt-für-Schritt) dokumentiert werden und keine Werkzeuge oder Funktionen.

  • Hilfestellung für die Gruppe der Anwender um Fehler vorauszusehen und zu vermeiden.

  • Der Gruppe der Anwender soll es freigestellt bleiben seine eigenen Erfahrungen zu sammeln. Es muß ihnen nicht klargemacht werden was sie für sich selbst entdecken können.

Quelle: docs.oasis-open.org mit Ergänzungen

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. TYPO3 oder einer Versionsverwaltung bzw. Source Code Management System 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.

Einarbeitung in das DITA Fachgebiet

Zum Einlesen in den Dita Standard 1.2 empfiehlt sich die Lektüre der Datei OASIS DITA1.2-spec.chm ⮷ 🇬🇧 oder XMLMind dita-1.2-specification.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.

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.

Es besteht die Möglichkeit mit dem ditaval Attribut dita Topics während der Transformation in verschiedene Ausgabeformate wie z.B. PDF oder EclipseHelp nach Zielgruppen gefiltert auszugeben.

Eine ausführliche Beschreibung ist im docs.oasis-open.org Archiv zu finden.

Editoren

Vom Prinzip her lässt sich jeder XML-Editor verwenden. Dazu sind die entsprechenden dita DTDs lassen vom docs.oasis-open.org Archiv herunterladen und in den jeweiligen XML-Editor einzubinden.

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 Open Tool Kit

Mit dem DITA Open Tool Kit (Open Source) können auf der Kommandozeile DITA konforme Inhalte in diverse Layout-Formate wie z.B. PDF, EclipseHelp, HTML, JavaHelp und transformiert werden. Das DITA Open Tool Kit erfordert eine vorhandene Java Runtime Environment (JRE) und ein kompatibles Java Development Kit (JDK). Das Dita OT Kit kann ohne administrative Rechte benutzt werden.

Dokumentationen produzieren

Louise Kasemeier (lone-dita) bietet eine sehr gute DITA Schritt-für-Schritt Anleitung anhand vom XMLmindEditor.

Nach der Zusammenstellung der *.ditamap mit den relevanten Tasks, Concepts, Referenzen usw. wird die Transformation in ein Ausgabeformat durchgeführt.

Transformation mit Hilfe der dost.jar Datei Steuerdatei

Diese einfach zu verwendende Transformation eignet sich gut dafür erstellte Ditamaps im Ausgabe Layout zu testen. Damit ist eine Erfolgskontrolle bei der Erstellung der dita konformen Dokumentation möglich. Weitere Transformationstypen (transtype's) sind zum derzeitigen Stand: docbook, eclipsehelp, xhtml, eclipsecontent, javahelp, htmlhelp, pdf, troff, wordrtf

Plugins

Das Dita Open Tool kann durch verschiedene Plugins erweitert werden. Das docbook2dita Plugin z.B. erlaubt die Transformation von DocBook Dateien in das Dita Format.

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. Desweiteren sollte Drag und Drop in die *.ditamap des verwendeten XML Editor funktionieren.

⚓︎

Literaturempfehlungen

Einsteiger

Fortgeschritten

DITA Einstieg

Fortgeschritten

Diese Revision wurde am 29. Oktober 2020 11:49 von juliusharpstedt erstellt.
Die folgenden Schlagworte wurden dem Artikel zugewiesen: Bildung