Monat: Mai 2009

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

DITA bietet bereits einige Attribute, die schon sehr viele wichtige Dinge in der technischen Dokumentation abdecken: product, audience, platform seien da als Beispiele genannt.

Wenn es um sehr firmenspezifische Dinge geht, benötigt man hier schnell eigene Attribute. Für mich persönlich sehr wichtig, sind auch vorgegebene Attributwerte, weil eine vorgegebene Auswahl immer sehr viel weniger fehleranfällig ist.

Was bedeutet Spezialisierung?

In DITA nimmt man etwas Vorhandenes, also einen bereits vorhandenen Topictyp (z.B. Concept) oder ein bereits vorhandenes Attribut, und leitet davon seine eigene Version ab: man spezialisiert. Inbesondere in Bezug auf Topictypen ist wichtig zu wissen, dass man Festlegungen der DTD von der man ableitet, nicht „aufweichen“ kann. Wenn ein Element <hups> in der Ur-DTD zwingend erforderlich ist, kann man es in der Spezialisierungs-DTD nicht optional definieren.

Attribute spezialisieren

Es gibts 2 Arten von Attributen, die man spezialisieren kann: props (speziell für Filtern) und base (Sinn und Zweck hat sich mir noch nicht erschlossen…). Da ich mein neues Attribut zum Filtern des Contents benutzen möchte, benutze ich daher das props-Attribut.

Schritt 1: Attribut deklarieren
Ich werde nun ein Attribut definieren, das beschreiben soll, für welchen Hilfekontext das Element gilt: für die Hilfe im Web oder für die Hilfe in der Software.

1. Zuerst erstelle ich eine Datei namens helpContextPropsDomain.ent mit folgendem Inhalt:



   Im ersten Teil lege ich den Namen des Attributs (help-context) fest und in meinem Fall auch 2 vordefinierte Werte (webpage, software).
2. Ich speichere die Datei im dtd-Verzeichnis des DITA-OT ab.

Schritt 2: Attribut der DTD bekannt machen

1. Nun öffne ich die concept.dtd und lege noch eine Sicherheitskopie von ihr unter anderem Namen ab Man weiß nie… ;).
2. Unter dem Bereich DOMAIN ATTRIBUTE DECLARATIONS füge ich ein:
   
SYSTEM "helpContextPropsDomain.ent"
>
%help-context-props-d-dec;
3. Unter dem Bereich DOMAIN ATTRIBUTE EXTENSIONS erweitere ich :
   

4. Unter dem Bereich DOMAINS ATTRIBUTE OVERRIDE erweitere ich :
   
&ui-d-att; &hi-d-att; &pr-d-att; &sw-d-att;
&ut-d-att; &indexing-d-att;&help-context-props-d-att;" >
5. Diese Schritte müssen nun für alle Topictypen wiederhiolt werden, für die man das Attribut braucht.

Schritt 3: testen 🙂

1. Ich erstelle eine XML-Datei auf Grundlage dieser DTD
2. Ich füge das Attribut _help-context=“webpage“_ in ein-Element ein
3. Ich jage das Dokument durch einen Validator – und wenn der nicht meckert, hat es funktioniert

Spezialisierung in XMetal DITA Edition
Der XMetal DITA Edition bindet ein DITA-OT ein. Wie es scheint benutzt er dieses ausschließich zum Generieren.
Die DTDs, die XMetal benutzt, liegen im Programmverzeichnis unter „…XMetaL 5\Author\DITA\DITA_OT_DTD\“<.

1. D.h. die oben erstellten bzw. bearbeiteten Dateien müss dort hinein kopiert werden.
2. XMetal neu starten
3. Ein Concept anlegen
4. Und sich freuen, dass man ein neues Attribut im Attribute Inspector sieht 🙂

Mehr zum Thema
In Eliot Kimbers Tutorial erfahrt ihr mehr zur Spezialisierung.

Ich bin ja keine Übersetzerin und mein Englisch-LK ist auch ne Weile her, aber diese externe Übersetzung meines deutschen Hilfetexts in das Englische hat mich stutzig gemacht.

Die Auflösung kommt nach dem nächsten Klick! 🙂 „Rätsel zum Freitag“ weiterlesen

Der Link ist essentieller Bestandteil der Online-Welt. Gerade bei der Topicorientierung, in der Information quasi auseinandergerissen ist, ist er die beste Navigationsmöglichkeit für den Leser und stellt einen Kontext her.

DITA ermöglicht einem einerseits manuell Links zu setzen oder sie automatisiert setzen zu lassen, indem man vorher den Beziehungsstatus definiert.

Heute gibt es erst einmal etwas zu den Links, die man als Redakteur selbst direkt einfügen kann.

<xref> – Inline-Links
Diese Links setze ich manuell mitten im Textfluss. Etwa so wie diesen hier. Dieses Vorgehen ist eigentlich allgemein bekannt.
Im Code sieht es so aus:

hier

Verlinken kann man alles von anderen Topics bis hin zu Webseiten (nur bei Links von generierten PDFs auf Online-PDFs muss man bei Verwendung des FOP aufpassen).
Generell ist das Verwenden von Inline-Links aber eigentlich nicht so toll:

• sie unterbrechen des Lesefluss und die Aufmerksamkeit des Nutzers. Will man den Nutzer wirklich mitten im Task in einen völlig anderen Kontext schicken? Eigentlich nicht. Höchstens wenn es sich um eine Handlungsvoraussetzung handelt.
• ein Topic ist durch einen Inline-Link in der Regel schlechter wiederverwendbar. Verwendet man es wieder, könnte der Link kaputt gehen, weil das Linkziel in diesem neuen Kontext nicht vorhanden ist.

<related-links>
In der manuellen Variante der „Related links“ fügt man den Tag <related-links> ein und setzt die Links in einzelne <link>-Tags oder in eine <linklist>. Das Gute an diesem Tag ist, dass er am Ende des Topics gesetzt wird, also den Nutzer nicht aus dem Kontext reißt. Aber auch in dieser Option steckt der Nachteil, dass die Wiederverwendung des Topics eingeschränkt wird.

Ich bin in den letzten Monaten mehr land unter als mir lieb ist und man sieht doch eindeutig an der Zahl meiner Blogeinträge, dass ich nach Feierabend kaum noch Energie für TR abseits meiner Arbeit aufbringe. Dabei habe ich doch gerade in dieser arbeitsreichen Zeit wieder einigen Stoff gesammelt 🙂

Tasks konzipieren
jeder Schreiber kennt das: da sitzt man also vor dem leeren Blatt / dem weißen Screen und muss irgendwie anfangen mit der Doku. Ich fange in der Regel so an, dass ich mich erst einmal selber als Dummy durch das Produkt klicke und mir Tasks notiere, die ich dokumentieren würde. Von Mike Hughes habe ich mir abgeschaut, die größte Prio auf die Tasks zu setzen, da sie für den Nutzer erst einmal das Wichtigste sind, denn dieser will in erster Linie etwas MACHEN.

Ideal für diese Vorgehensweise ist der IBM Task Modeler, ein eclipse-basierte Editor mit dem man Topics und ihre Beziehungen / Hierarchien in einer Map visualisieren kann. Man hat die Wahl zwischen einer Baumansicht und einer Listenhierarchie-Ansicht. Hier mal ein sehr einfaches Beispiel in einer Baumansicht:

Per Tastenkombination kann man sehr schnell Child-Topics ( Strg+Pfeil nach unten) oder Schwester-Topics einfügen und somit sehr zügig arbeiten. Man kann die Topics außerdem in der Anordnung per „Drag and Drop“ wild verändern, was meiner Arbeitsweise sehr entgegen kommt.

Ich sammele immer zuerst alle Informationen bzw. Topics und schiebe /lösche / erweitere /verteile dann so lange bis ich die perfekte Struktur finde. Gleichzeitig kann ich im Modeler auch schon alle Metadaten für die Topics bearbeiten oder die Reltables.

Tasks exportieren

Wenn ich nämlich all das fertig habe, kann ich ganz einfach hergehen und diese schöne Struktur mit allen Informationen exportieren: File > Export from Model > Stub Topic Files

Der Task Modeler generiert mir sogenannte Stub Files, d.h. Dateigerüste für jedes Topic. Diese Dateigerüste enthalten auch direkt alle Informationen, die ich eben eingegeben habe. Also für alle Tasks werden dann echte Task-Dateien mit den eingegebenen Titeln, Attributen etc. angelegt. Zusätzlich ich kann festlegen, dass in der exportierten Map auch automatisch die Referenzen auf die Stub Files gesetzt werden und die Dateinamen der Stub Files ihrem Topictyp entsprechen, d.h. dass beispielsweise alle Task-Dateien mit dem Präfix t_ im Ordner tasks abgespeichert werden. Und zack – hab ich die Grundlage zum weiteren Arbeiten.

Vorsicht ist allerdings speziell im Deutschen geboten, wenn man Umlaute im Titel verwendet, denn dieser ist auch Grundlage für die Dateibenennung und ID-Vergabe. Und der Task-Modeler schreibt diese Umlaute auch gnadenlos in den Dateinamen und in die ID: das Topic Lösung finden bekommt dann eben auch den Dateinamen t_lösung_finden.dita. Früher oder später führt so etwas immer zu Problemen, je nachdem wo die Dateien weiterverarbeitet werden. Mein Workaround war irgendwann, dass ich Umlaute in den Titeln einfach ausgelassen habe und sie später nach dem Export im Editor einfügte. Das ist schneller als alle Dateinamen und noch die ID zu bearbeiten.

Fazit – Task Modeler rockt!

Der Task Modeler ist eine super Unterstützung in der Konzeptionsphase einer DITA-basierten Dokumentation. Das Konzipieren ist schön einfach und am Ende kommt auch per Knopfdruck direkt eine schöne Arbeitsgrundlage raus, nämlich die Map plus Dateien.

Das Handling der Eclipse-Oberfläche ist allerdings für Nicht-Entwickler etwas gewöhnungsbedürftig – diese ganzen Panels sind einfach etwas verwirrend. Wärmstens zu empfehlen ist das Task Modeler Tutorial – diese Zeit sollte man sich nehmen, wenn man effektiv mit dem Tool arbeiten möchte.

Noch nicht getestet – Import von bestehenden Maps

Angeblich kann man andere Maps auch in den Modeler importieren, was sich natürlich für strukturelle Nacharbeiten sehr empfehlen würde. Allerdings habe ich das bisher noch nicht machen müssen 🙂