IBM Task Modeler: die Anfänge einer Dokumentation

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 🙂