tekom-Jahrestagung 2009 #2 – Dating DITA

Ich war in sage und schreiben einem DITA-Vortrag. Erstens gab es davon gar nicht so viele („Der Hype flaut ab“, wie ein CMS-Hersteller mir bestätigte), zweitens waren die meisten davon eher auf einem Anfängerlevel.

Bei diesem Vortrag war ich fast geneigt nicht hinzugehen, da mir der Titel zuerst zu gewollt witzig vorkam. Ein Blick in den Tagungsband hat mich dann doch überzeugt.

Hier ging es um einen rein semantischen Blick auf DITA – was ich zur Abwechslung mal sehr erfrischend fand. Das ganze hier spielte hier keine Rolle:  „Dann kannst du auch noch das machen – und Maps und Conref… und DITAVAL… das Open Toolkit und Spezialisierung“

DITA – die Informationsarchitektur

Im Blickpunkt stand: die Sicht des Redakteurs. Kann man als Redakteur relativ einfach mit der DITA-DTD arbeiten? Erschließen sich bspw. Elementnamen sofort („Self-documenting structure“), braucht man am Ende keinen Styleguide mehr?

Ralf Steiner und sein Team haben sich DITA angeschaut und ihnen ist Folgendes aufgefallen

  • endlos viele Titles (searchtitle, navtitle, title) und keine gute Abgrenzung
  • Abgrenzung zwischen abstract und shortdesc unklar
  • das Schachteln von versch. Topictypen ist fragwürdig.
    Ich finde es schon fragwürdig, zwei tasks ineinander zu schachteln.
  • Unterschied zwischen choices und choicetable ist unklar.
    Für mich ist das eine Layoutsache, manchmal lassen sich Handlungsvarianten besser tabellarisch darstellen. Aber natürlich ist das wieder so eine Sache, weil man ja hier semantisch denken sollte und nicht layoutorientiert. Doch zu 100% lässt sich das nie trennen, wie ich festgestellt habe.
  • Was soll das info-Element, wo doch ein Task keine Hintergrundinfo geben soll?
    Nun ja, ganz ohne Hintergrundinfo geht es eben nicht. Ich platziere hier auch nur Hintergrundinfo, die sich auf den spezifischen Schritt bezieht, daher hab ich an dem Element nichts auszusetzen.
  • Wozu braucht man steps-unordered?
    Ja, allerdings, wozu? Ob die Steps später nummeriert werden oder als Bullets dargestelt werden, entscheidet sich doch erst beim Generieren.
  • Die Concept-Topics sind eine Glaskugel aus der man alles ableiten kann.
    Oh ja! Ich habe bis heute nur eine vage Idee, wie ich Concepts wirklich standardisieren soll.
  • Die Benennung der Element ist inkonsistent bzw. nicht sprechend. Man könnte eine dl auch deflist nennen, äquvalent zur linklist.

Ich füge noch hinzu:

  • Abgrenzung zwischen context und shortdesc ist schwammig.
  • Wozu werden related-links ermöglicht, wenn man doch nur die Wiederverwendung damit erschwert und Relationship tables eigentlich viel besser sind?
  • Für Tasten gibt es kein Element! Wie soll den Software-Dokumentation ohne Tasten gehen? Ich habe uicontrol daher eben auch hierfür als Auszeichnungselement definiert.
  • Ich kann das p überall benutzen, aber sollte ich auch? Zum Beispiel innerhalb von note, li, shortdesc, context etc.

DITA – ohne Styleguide? Lieber nicht…

Das ist das Fazit von Ralf. Und da kann ich mich voll und ganz anschließen. Ich habe auch zuerst ein Funktionsdesign erarbeitet und dann quasi mit DITA verheiratet. Es sind einfach zu viele Elemente, die nicht eindeutig out-of-the-box zu befüllen sind. Und man hat ja auch bei der Strukturierung immer noch sehr viele Freiheiten, die am Ende dann auch nicht mehr wirklich Standardisierung bedeuten.

Insgesamt ein sehr guter und gut gehaltener Vortrag, der sich mal dem gewidmet hat, auf das es am Ende ankommt: kann man gut damit arbeiten?

PS: Zu viele Bilder der personifizierten DITA sind dann irgendwann auch nicht mehr witzig…

Task-Grenzen

Beim Texten von Tasks gibt es etwas, was mich als Redakteur von Software-Doku seit den Anfangstagen als TR regelmäßig verrückt macht: wo hört ein Task auf und wo beginnt der nächste? Speziell bei Handlungen, die im Großen und Ganzen dasselbe Ziel haben, aber die man auf verschiedenen Wegen erreichen kann.

1 Handlung = mehrere Varianten

Ein gängiges Beispiel ist das Einfügen von Bildern, z.B. in ein Blog oder eine Website.

Ziel: Bild in den Artikel einfügen

Möglichkeiten zur Zielerreichung:

  • Bild vom PC hochladen
  • Bild aus dem Web verlinken
  • Bild aus vorhandener Galerie einfügen

Die Handlungen sind in den ersten Schritten typischerweise identisch, aber unterscheiden sich dann in den meisten folgenden Schritten. Nur das Ziel ist am Ende dasselbe: ein Bild wurde eingefügt. Ich bin nie so ganz schlüssig, was ich in solchen Fällen tun soll.

Option 1:Rigoroses Splitten

ich teile das ganz rigoros in drei Topics auf. Der Nutzer sieht ganz spezifisch an der Topic-Überschrift um was es geht.

  • Bild vom PC hochladen
  • Bild aus dem Web verlinken
  • Bild aus vorhandener Galerie einfügen

Das Problem ist, dass ich auf diese Weise ganz schön viele Topics produziere, die den Nutzer fast erschlagen. Zudem gibt es auch Nutzer, die nur wissen, dass sie ein Bild einfügen wollen, aber mit den drei Optionen einfach so nichts anfangen können. Und prinzipiell sucht wahrscheinlich auch ein erfahrener Nutzer eher nach „Bild einfügen“ als nach „aus dem Web verlinken“.

Option 2: In ein Topic verpacken

Es gibt einen Ort an dem der Nutzer nachschaut – bingo, da sieht er alles was zu dem Thema wissen muss.

  • Bild einfügen

Das Problem ist, dass man so unter Umständen ganz schön lange Topics produziert – zudem kann man es kaum in die SITA-Struktur packen. Es gibt zwar Handlungsvarianten (choice), aber die beziehen sich meist auf einen Handlungsschritt, und nicht einen ganzen Handlungsstrang. Sowas wäre mir am liebsten:


Um ein Bild hochzuladen, wählen Sie eine der folgenden Möglichkeiten:



Um eine eigene Datei hochzuladen...
...



Um eine Datei aus dem Web zu verlinken...
...



Aber das lässt DITA nicht zu. Mir ist auch klar warum: damit fällt es einem leichter mehrere Topics in eins zu verpacken. Und man will ja immer nur ein Thema pro Topic. Dummerweise ist das Leben nicht immer so einfach. Hier würde ich mir zumindest mehr Flexibilität wünschen.

Fazit
Hält man sich streng an die DITA-Informationsarchitektur kann man eigentlich nicht anders als das auf 3 Topics zu splitten. Aber aus Nutzersicht gefällt es mir nicht.

Breadcrumbs in DITA-XHTML

Der Name Breadcrumb-Navigation wurde in Anlehnung an das Märchen Hänsel und Gretel der Brüder Grimm gebildet, in dem die in den Wald geführten Kinder Brotkrumen (englisch breadcrumbs, plurale tantum) auf den Weg streuen, um den Weg zurück zu finden (PediaWiki)

Mir geht es speziell um die „Location-Breadcrumbs“, d.h. ich möchte, dass in meiner HTML-Hilfe sichtbar ist, wo in der Hierarchie sich der Nutzer gerade befindet.

Ein sehr klassisches Instrument in der Nutzerführung, das aber lustigerweise in dem Standard-XHTML-Output gar nicht drin ist.

Nachdem ich etwas recherchiert habe, bin ich recht schnell auf ein relativ frisches Plugin gestoßen, das genau das macht: Ancestors

So sieht eine Topic-Seite in HTML dann auch aus, wenn man sie generiert:

Installation

Die Installation ist denkbar einfach:

  1. Herunterladen.
  2. Das Verzeichnis qwcode.ancestors in das plugins-Verzeichnis im DITA-OT kopieren.
  3. Im DITA-OT-Verzeichnis eine Shell öffnen und ant -f integrator.xml eintippen.
    –> In der Datei dita2xhtml.xsl sollte das Stylesheet des Plugins nun referenziert werden.
  4. Im Verzeichnis qwcode.ancestors eine Shell öffnen und ant buildDemo eintippen.
    –> Hier sollten nun im Unterverzeichnis demo/xhtml die XHTML-Dateien generiert werden.

Das ganze hat bei mir echt gut geklappt und daher spreche ich eine eingeschränkte Empfehlung aus. Die Einschränkung folgt auch sofort.

Bug bei Verwendung von reltables

Aktuell werden leider bei allen Topics, die in Reltables referenziert werden, die Breadcrumbs falsch dargestellt, so wie in diesem Beispiel, in dem die Startseite „Index“ zweimal verlinkt wird. Das zu fixen ist sicherlich kein Hexenwerk, aber ich habe gerade keine Zeit…  Wenn das aber gefixt ist, empfehle ich absolut uneingeschränkt 🙂

Links in DITA #3 – Relationship tables

Mit den so genannten Relationship tables (reltable) kann man die Beziehungen zwischen Topics definieren. Hiermit implementiert man Verlinkungen, die nicht durch die Hierarchie (oder die anderen collection-types) festgelegt ist. „Links in DITA #3 – Relationship tables“ weiterlesen

Links in DITA #2 – Hierarchien und collection-type

Ich habe bereits vorgestellt, welche Möglichkeiten des manuellen Verlinkens es gibt. Wie gesagt, erschwert diese Methodik die Wiederverwendung eines Texts. Da Wiederverwendung jedoch einer der Kernpunkte von DITA ist, gibt es natürlich auch hier Mittel und Wege. Und zwar indem man die Verlinkungregeln in die Maps auslagert. So kann man auch nur das verlinken, was in der Map drin ist und läuft nicht Gefahr tote Links zu erzeigen.
„Links in DITA #2 – Hierarchien und collection-type“ weiterlesen