Topic-Orientierung

Das Topic

Ein Wort, das nun spätestens seit DITA eingeschlagen ist wie eine Bombe und in vieler Munde ist. In der Welt der Software-Hilfen ist das Topic an und für sich schon länger präsent, da dort die Hilfe in Form von Einzelartikeln präsentiert wird. Oftmals wurde hier aber nicht topic-orientiert geschrieben, sondern eben wirklich nur die Präsentationsform der vielen einzelnen Artikel gewählt.

Doch Topic-Orientierung bedeutet vor allem, dass ein Topic ein Thema behandelt. Und zwar ein einziges, das für sich alleine stehen kann: beispielsweise muss die Beschreibung eines Luftballons getrennt von sein von der Beschreibung wie man ihn aufbläst. Außerdem muss ein Topic kontextunabhängig sein, d.h. ich muss die Beschreibung zum Aufblasen auch verstehen können ohne das Topic mit der allgemeinen Beschreibung gelesen zu haben. Schließlich ist ein Topic in einer Online-Hilfe auch immer ohne Kontext erreichbar.

Ein weiteres Kernkonzept ist auch, dass ein Thema nur in einem Topic beschrieben wird – und nur in einem! Man schreibt also nicht dreimal dieselbe Information auf, weil das eine für die HTML-Hilfe ist, das eine für das Quickstart-PDF und das andere für das Kompletthandbuch-PDF. Man hat eine Quelle!

Das bedeutet im nächsten Schritt aber auch, dass man Topics idealerweise ohne Hinblick auf die Erscheinungsform schreibt , d.h. als Autor bin ich losgelöst von der Endausgabe. Das Topic muss in möglichst vielen Dokumentationsprodukten funktionieren können, in verschiedenen Strukturen, sei es in Handbuch A oder Handbuch B, und in verschiedenen Endformaten, sei PDF, HTML oder CHM.

Die Topic-Klasse

Eine Topic-Klasse ist eine Bauanleitung für verschiedene Topic-Arten. Ich stelle z.B. fest, dass in meiner Doku ein bestimmtes Schema vorherrscht, z.B. Frage-Antwort und dann halte ich das als Schema fest und beschreibe genau wie man diese Topics nach dem Schema aufbaut.

Das Festlegen von Topic-Klassen erleichtert einerseits das Schreiben (ich weiß, wo was hingehört) und andererseits das Rezipieren des Textes (ich erkenne Muster und finde mich besser zurecht).

In DITA gibt es drei Topic-Klassen:

  • Concept: Für Hintergrundinformationen, also den klassischen Prosa-Text.
  • Task: Für Handlungsanleitungen, also den klassischen „Klicken Sie auf…“-Text.
  • Reference: Für Übersichten, Referenzen, Tabellen, z.B. Befehlsübersichten.

Was soll der Hype?

Die Frage ist nun natürlich, was das alles bringt:

  • Fröhlicher Nutzer: Die Nutzer lesen selektiv und nicht linear. Ein kompakter, auf ein Thema konzentrierter Informationshappen kommt diesem Verhalten entgegen. Will ein Nutzer was MACHEN, liest er Artikel mit der Überschrift „XY machen“, also Tasks, und will er was genauer WISSEN, liest er Artikel mit der Überschrift „XY – die Grundlage“, also Concepts.
  • Fröhlicher Autor: Ich muss nicht für jedes Topic das Rad neu erfinden, sondern orientiere mich an den Klassen. Topics erleichtern mir außerdem die Wiederverwendung von Inhalten (wenn ich es richtig mache!). Endlich nicht mehr alles doppelt und dreifach schreiben, sondern nur einmal. Endlich nicht mehr eine Änderungen an zwei Stellen durchführen und eine vergessen, sondern einmal und damit überall ändern.

Klingt einfach…
… isses aber nich‘ 😉 Es gibt ein paar Spielregeln zu beachten, die für alle gelten und ein paar, die sich jede Firma selbst schreiben muss. Darum geht es in der nächsten Zeit.

Lokalisieren mit DITA

Eigentlich ist es eine ganz einfache Sache bei DITA: man setzt xml:lang-Attribut auf die gewünschte Sprache/Sprachvariante und zack, sind die Standardtexte (so etwas wie „Achtung“, „Voraussetzung“ u.ä.) lokalisiert. DITA bringt schon eine ganze Latte von Sprachdateien mit sich, die diese Texte enthalten und zwar unter DITA_OT/xsl/common.

Nun habe ich diese Dateien erweitert und das hat in der Standardsprache meiner Pilot-Doku (en-us) auch super geklappt das einzubinden. Als ich nun diese Doku in das britische Englisch (also en-gb) übersetzen wollte, wurden die Standardtexe weiterhin aus der Sprachdatei für en-us eingebunden. Ein kurzer, erfolgreicher Test mit der Lokalisierung ins Deutsche hat ergeben, dass die Lokalisierung an und für sich schon funktioniert, aber nur die Sprachvariante en-gb nicht.

Und was war des Rätsels Lösung? In der strings.xml wird definiert für welche Sprache welche Sprachdatei verwendet werden soll und da stand glatt für alle Sprachvarianten einer Sprache immer eine „Hauptsprache“ drin. Das heißt in allen Englischvarianten stand en-us als Standard drin, bei Deutsch beispielsweise de-de und so weiter.

Natürlich war das nirgends dokumentiert, aber dank Community war auch das dann gelöst – und zwar so:

ALT: <lang xml:lang=“en- gb“ filename=“strings-en-us.xml“
NEU: <lang xml:lang=“en- gb“ filename=“strings-en-gb.xml“ />

Ich hatte schon etwas Angst bekommen, dass das Problem komplizierter ist, weil es einige Artikel gab, in denen stand, dass beim PDF-Generieren die Lokalisierung anders läuft. Allerdings ist das nur so, wenn man pdf2 nutzt. Immerhin etwas Gutes hatte es an dieser Stelle, dass wir noch FOP nutzen 😉

GeFOPpt

Wir befinden uns mit DITA noch in einer Pilotphase, d.h. das ganze muss erst einmal so wenig wie möglich kosten, weil man ja nicht weiß, ob der Weg vielleicht doch nicht der Richtige ist. Das heißt also wir nutzen einfach das, was im Open Tool Kit mitgeliefert wird.

Beim PDF-Output hat sich aber ein Layoutmangel gezeigt, der mir die ganze Zeit schon Kopfzerbrechen bereitet und zwar die Absatzkontrolle. Ganz häufig wird zwischen Überschrift und dazugehörendem Text ein Seitenumbruch gemacht (ist das dann auch ein Schusterjunge?). Jedenfalls ging es mir nicht in den Kopf, dass so ein typografischer Grundsatz bei den vorgefertigten DITA-Stylesheets nicht dabei ist. Flugs mal in die XSL-Dateien geschaut, hab ich festgestellt, dass das entsprechende FO-Attribut keep-with-next.within-page sehr wohl auf always gesetzt ist.

Aaah, welcher komische Bug verursacht das denn dann?

Das gute alte 2003
Tja, nach einigem Googlen konnte ich feststellen, dass FOP 0.20.5 dieses Attribut nicht unterstützt. Kein Wunder, dass es nicht klappt. Aber noch seltsamer finde ich eigentlich, dass das DITA Open Tool Kit diese uralte Version von 2003 mitliefert. Das ist doch echt seltsam. Vor allem findet man nirgends eine Info dazu, warum diese Version benutzt ist oder ob und welche Probleme man hat, wenn man die neue 0.95 nutzt.

Ich habe die schwere Vermutung die DITA-Leute sind gar nicht so open-source-geil, sprich: keinen Bock auf Frickeln.

Übrigens finde ich diesen Sprung in der Versionierung auch sehr witzig: eben noch 0.20.5 nun schon ne 0.9er 😉

fop 0.95 ins DITA-OT
Also nix wie los und testen, ob man die 0.95 nicht einfach selbst inetgrieren kann. Leider musste ich mich dazu aber nun mal intensiv mit der DITA-Installation beschäftigen. Bisher hatte ich hier immer den XMetal DITA Edition laufen und der hat einem solcherlei Ding gut abgenommen.

Ich habe mich vor allem an diesen Thread gehalten (http://tech.groups.yahoo.com/group/dita-users/message/8222) und habe also wild in den Konfigurationsdateien herumkonfiguriert, bin aber gnadenlos gescheitert. Am Ende des Threads folgt übrigens das Resümmee, dass selbst wenn man 0.95 zum Laufen bekommt, die Ergebnisse eh nicht so berauschend sind.  Das motiviert zum Aufgeben! Der echte Gnadenschuss für FOP bei uns folgte aber als das Schriftenproblem auftauchte. Doch dazu später mehr…