XHTML-Output anpassen #2 – Wie mache ich einen Override?

Ich habe nun damit angefangen Anpassungen vorzunehmen.

Im Groben sind dazu folgende Schritte notwendig:

  1. Plugin-Verzeichnis und Dateien anlegen.
  2. Plugin integrieren.
  3. XSL anpassen.

Plugin-Verzeichnis und Dateien anlegen

Dazu habe ich unter DITA_OT/demo ein Verzeichnis meinxhtml für meine Overrides angelegt, d.h. hier liegen meine Anpassungen für den XHTML-Output. Für DITA ist das einfach ein Plugin.

In diesem Verzeichnis befindet sich ein Ordner mit meinen XSL-Dateien und die plugin.xml. In dieser Datei muss man dem DITA-OT sein Plugin quasi bekannt machen. Das sieht dann so aus:

Plugin integrieren

  1. Hierzu öffnet man sich eine Konsole im DITA-OT-Verzeichnis und führt folgenden Befehl aus: ant -f integrator.xml
    Ob das wirklich geklappt hat, kann man in der Datei xsl/dita.2xhtml überprüfen. Dort sollte die XSL-Datei nun über ein <xsl:import> referenziert werden.

XSL anpassen

Jetzt kommt der wirklich spannende Teil. Wie schon erwähnt, wird das meiste über die Datei dita2htmlImpl.xsl gemacht. Wenn ich also nun etwas Bestimmtes modifizieren will, z.B. dass nach dem Titel einer Note kein Doppelpunkt kommt, gehe ich wie folgt vor.

  1. Ich schaue über Firebug in den Quelltext des Outputs, um zu sehen, ob der Bereich irgendwie besonders ausgezeichnet ist. Im Falle der Note sehe ich, dass der Note-Title in einem span-Tag steht und mit der CSS-Klasse notetitle ausgestattet ist.
  2. Über diese Hinweise finde ich dann in der XSL-Datei das entsprechende XSL-Template für diesen Bereich:
  3. Ich kopiere nun das komplette Template in meine mein_xhtml.xsl.
  4. Um den Doppelpunkt zu entfernen, lösche ich die entsprechenden Anweisungen. In diesem Beispiel also: 

  5. Diese Änderung speichern.
  6. Output generieren.
    Und nun sollte der Doppelpunkt verschwunden sein. Leider muss man den Doppelpunkt für alle Note-Typen entfernen, die es gibt, also für Tipps, Warnungen etc.

Hiermit lässt sich schon mal sehr viel machen. An die Grenzen der Overrides kommt man beim OT 1.3, wenn es um die Anpassung des Inhaltsverzeichnisses geht. Hier funktionieren Overrides nämlich leider, leider nicht. Doch dazu ein anderes Mal mehr 🙂

tekom-Jahrestagung 2008 #5 – Finale

Ich habe einen Haufen Vorträge gesehen und nachdem ich nun meine Highlights schon beschrieben habe, kommen wir zu der Kategorie „Ferner liefen…“. Hier findet sich sowohl Gutes als auch Schlechtes 😉

Adobe Air, eine neue Basis für Onlinehilfen?

Der erste Vortrag meines Tagungsprogramms lieferte einen gute Überblick über das was Air ist, was es kann und wozu es gut ist. Die Folien gibt es online.

Content Reuse – Zusammenspiel von Software-Entwicklung und Technischer Dokumentation

Definitiv eine der größten Enttäuschungen (neben der Tatsache, dass ich in manche Workshops nicht mehr reinkam). Es ging hier um ein Beispiel in dem für die Dokumentation die strukturierten Daten, die schon bei den Entwicklern vorkamen, wiederverwendet werden konnten. In diesem Fall handelte es sich um 15.000 Fehlermeldungen, deren Kodierung und Text über XML dann an die Doku weitergereicht wurde, auf dass diese die entsprechenden Erklärungen schreibt. Klar, das ist Reuse, aber definitiv eine Variante, die in der freien Wildbahn echt nicht oft auftaucht. Und in der Vortragsbeschreibung kam das auch ganz klar nicht raus. Da haben sehr viele etwas anderes erwartet 🙁

Von 0 auf XML in 80 Tagen: Einführung eines XML Redaktionssystems auf Basis von Funktionsdesign

Hier hat der Kaffeemaschinenhersteller Jura vorgestellt, wie die Doku sich bei ihnen entwickelt hat. Irgendwann wurde ein Cut gemacht bei dem entschlossen wurde, dass nicht mehr Entwickler die Doku schreiben *lach*. Es wurde ein Funktionsdesign entwickelt, das dann auf alle neuen Anleitungen angewandt wurde. Irgendwann war alles an Doku standardisiert und dann kam man auf die Idee ein CMS einzusetzen. Und nachdem man sich für ein CMS entschieden hatte, dauerte es tatsächlich nur 80 Tage bis es einsatzbereit und mit bisherigem Content angefüllt war. Herrlich! Genauso sollte es laufen. Naja, bis auf die Tatsache InDesign einzusetzen… Aber ansonsten bin ich neidisch 🙂

Wissensmanagement bei dezentraler Dokumentationserstellung für multiple Märkte, Marken und Sprachen

Die Essenz dieses Vortrags war, dass jedes Wissen, dass in einem Prozess wichtig ist, auch in diesem Prozess verankert sein muss. Ein durchaus interessanter Ansatz. Sehr schön fand ich den Begriff „Denk-dran-Lösungen“: er wurde hier für alle Informationsinseln verwendet, die sich mit der Zeit in einem Unternehmen entwickeln. Ein bisschen schade fand ich, dass der Redner Wikis komplett als Lösungswegs ausgeschlossen hat, weil sie zu „unstrukturiert“ wären und ja auch bei der Wikipedia nur 1% der Nutzer auch aktiv wären, was bei einer Firma dann auch nichts bringen würde. Aus eigener Erfahrung kann ich sagen, dass die Wikipedia nicht mit einem Wiki in einem Firmenumfeld vergleichbar ist. Letzten Endes lebt jedes Wissensmanagementsystem davon es gut an die Mitarbeiter zu vermarkten, sei es ein schnödes Wiki oder irgendetwas Kommerzielles.

An overview of localization in Latin America

Der Titel sagt genau worum es ging, aber noch treffender wäre der Begriff „localization industry“ gewesen. Ich hatte mir erhofft zu hören, was es für Strategien oder Tipps gibt, wenn man für Lateinamerika lokalisieren muss. Aber es ging wirklich nur um die Lokalisierungsindustrie dort. Das einzig Interessante war hier die Anmerkung, dass man sich als Unternehmen durchaus mal überlegen solle, ob es nicht effizienter und qualititatv besser wäre, die Lokalisierung in die jeweiligen Länder zu geben. Mir kam es alles in allem mehr wie eine Marketingveranstaltung für die Lok-Industrie da drüben vor.

Writing for an International Audience

Gute Zusammenfassung dazu wie schlechte Doku und auch Gedankenlosigkeit die Übersetzungskosten in die Höhe treiben können und am Ende vielleicht doch nur Müll rauskommt, weil eben Müll reinkam. Schönstes Rechenbeispiel: wie die Änderung eines Field Labels am Ende 5500$ kostet 😀

Zielgruppen im Fokus – Zielgruppendefinition in der Technischen Dokumentation

Hm ja, das Übliche eigentlich:

  • site visits
  • workshops
  • Fragebögen
  • Communities
  • Usability-Tests
  • Auswertung der Definitionen von Marketing und Vertrieb

Interessant war der Ansatz, dass man festlegen sollte, welche Zielgruppe strategisch wichtig für das Produkt ist (sowas macht dann wahrscheinlich das produktmanagement) und dann die Redaktion deren Kommunikationsbedürfnisse ermittelt. Einfaches Beispiel: ein Flugzeugtechniker braucht für die tägliche Arbeit kein umfangreiches Handbuch, sondern vielleicht eher eine Loseblatt-Sammlung mit Checklisten.

Das Deutsch der Technischen Redaktion

Bei einer Kaffeepause erzählte mir eine Kommilitonin, dass Prof. Baumert aus Hannover ganz tolle Vorlesungen halten soll. Und so bin ich ganz spontan hineingelaufen – der Vortragsraum war schon 10min vor Beginn randvoll. Ich war hin und weg: er legte los mit den philosophischen Grundlagen, die letzten Endes unser alle Muthig+Schäflein-Armbruster zum Designen des Funktionsdesigns verleiteten. Supertoll vorgetragen und wirklich interessant, weil ich bisher eigentlich immer nur wusste, dass das Funktionsdesign aus der Sprechakttheorie hervorgeht. Aber mehr auch nicht.

Leider musste ich während des Vortrags wg. eines Termins raus. Sehr schade!

Fazit

Ich war teilweise doch sehr enttäuscht darüber, wie sehr manche Vortragsbeschreibungen von der Realität abwichen und man dann in einem Vortrag nach 5min merken musste, dass man wohl in die Falle getappt war.

Leider sind auch einige Vorträge ausgefallen, die ich sehr gern gehört hätte.

Alles in allem fand ich es aber trotzdem sehr gelungen. Ich hatte einige schöne Highlights, habe alte und neue Bekannte getroffen und nächstes Jahr werde ich wohl hoffenltich auch dazu kommen mehr von Wiesbaden zu sehen als die Messe und das Hotel 😉

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.

Screenshots ändern leicht gemacht

Jeder Redakteur für web-basierte Software kennt das Problem, dass die Software, die man zum Doku schreiben benutzt, oft etwas anzeigt, was der Kunde in der Doku so nicht sehen soll.
Zum Beispiel steht irgendwo noch „Beta-Version“ im Text oder es werden Testdaten angezeigt („Sie sind als Test Testosteron eingeloggt.“). Man macht also einen Screenshot und ändert den Text ziemlich umständlich in Photoshop. Kurz: eines der nervigen Elemente im Redakteursalltag.

Für die Webentwicklung nutze ich den Firebug schon recht lange. Das ist ein Firefox-Addon mit man dem das HTML, CSS und Javascript einer Seite live editieren kann. D.h. man kann beispielsweise die Farbe ändern und es wird einem direkt im Browser angezeigt, wie sich das auf die Seite auswirkt. Das Add-on ist vor allem zum Fehlerfinden und CSS-Ausprobieren außerordentlich praktisch.

Und bis heute bin ich nicht drauf gekommen, dass man Firebug eben auch dazu nutzen kann, das ganz oben genannte Problem zu umgehen (zum Glück war einer meiner Kollegen so schlau). Man editiert die Seite im Firebug und ersetzt oder löscht den unerwünschten Text. Ich habe hierzu einfach mal den Header-Text dieses Blogs geändert.

So kann man direkt einen Screenshot machen bei dem man danach nicht in Photoshop herummachen muss bis man die richtige Schrift und Schriftgröße hat usw.

Dass ich da nicht früher drauf gekommen bin… Liegt vielleicht auch daran, dass es ne Weile her ist, seit ich das Problem hatte, da ich ja kaum noch Kundendoku schreibe.

PS: Nein, das ganze gibt nicht für den Microsoft Internet Explorer. Und wer’s noch nicht wusste: der IE ist doof 😉