topichead, topicref – Konfusion

Das Problem mit der Strukturierung, das ich unlängst hatte, ist tatsächlich nicht so einfach zu lösen. Kurzzusammenfassung: Es ging darum zwei Unterkapitel in einem Oberkapitel zusammenzufassen, das selbst aber eigentlich keinen Inhalt enthält.

title-only topics

Es gibt einerseits den Ansatz  sog. title-only Topics zu benutzen, die lediglich den Titel und eine short description enthalten. Damit kann man dann die gewünschten „leeren“ Oberkapitel erzeugen. Einige argumentieren hier, dass man so eine <shortdesc> auslesen kann, um sie bei Bedarf anzuzeigen, z.B in einer Online-Hilfe. Das ist für mich schon ein smartes Argument, das dem Nutzer hier und da nützen kann. Ein Topichead hat eben keine Beschreibung.

Keine unnötigen Topic-Hülsen!

Jedoch wiegt es für mich schwerer, was für ein Wirrwarr dann auf Erstellerseite entsteht. Ein Topic mit nur einem Titel als Inhalt ist für mich kein Topic, da es kein abgeschlossenes Thema beschreibt o.ä. Punktum! Wenn man mit title-only Topics auch nur anfängt landet ganz man schnell in einem Haufen eigentlich inhaltsleerer Topics und das sollte man meiner Meinung nach tunlichst vermeiden.

Keine Oberkapitel mehr?

Andere Stimmen sagen, dass man einfach davon wegkommen sollte, solche „leeren“ Oberkapitel überhaupt zu benutzen. Aber gerade in klassischen Handbüchern finde ich das irgendwie kaum machbar, ohne dass der Nutzer leidet (wer sich für eine längere Diskussion interessiert, bitte hier lang zur YahooGroup).

Kurzum

Ich habe immer noch keine Lösung. Ich kann aktuell nur hoffen, dass das <topichead>-Verhalten in einer der nächsten OT-Versionen geändert wird. Aktuell fungiert ein <topichead> eben einfach nur als Zwischenüberschrift, jedoch ohne Link, sowohl im PDF als auch im HTML. Oder ich mach’s halt selber 🙁

Was war zuerst: die Struktur oder das Topic?

Für die technische Doku bin ich nun ein absoluter Anhänger der Topicorientierung. Der Anspruch ist hier nicht für eine bestimmte Ausgabe zu schreiben, sondern die Bedienung eines Produkt zu beschreiben und ggf. die Hintergrundinformationen, die man dazu benötigt. Aus diesen Beschreibungen kann man sich später die verschiedensten Dokumentypen zusammenbauen, vom Schnell-Start-Guide bis zum Kompletthandbuch.

Nun starten die meisten Leute eine traditionelle Doku (also ein klassiches Word – oder Framemaker-Handbuch) damit ein Inhaltsverzeichnis zu erstellen. Im Endeffekt ist das auch nicht der schlechteste Ansatz, nur funktioniert er mit Topicorientierung zusammen nicht so gut, wie ich feststellen konnte.

Denn so bald man anfängt sich auf die Endausgabe, also z.B. das Benutzerhandbuch, zu konzentrieren, fängt man an, die Topics so zu schreiben, dass sie in die Struktur reinpassen, die man sich vorher zusammengestrickt hat. Aber so passiert es eben auch leicht, dass sie später in andere Strukturen, für die man das Topic braucht, eben nicht reinpassen. Man fällt selbst so schnell in die lineare Struktur hinein, dass man die Topicorientierung sehr leicht aus den Augen verliert.

Deshalb heißt es für mich ganz klar: zuerst kommt das Topic und später irgendwann die Struktur in der es zufällig auch existiert.

Topics strukturieren

Eine typische Doku-Situation geht so: Man hat zwei Kapitel, die inhaltlich unter einen Oberkapitel passen und um die Struktur übersichtlicher zu machen, packt man die Zweikapitel mit ihren Überschriften unter eine Ober-Überschrift (siehe unten).

1 Installation
1.1 blubTunes installieren
So installieren Sie…bla
1.2 blobTunes installieren
So installieren Sie…

Ein Problem stellt sich mir aber dar, wenn ich so etwas in DITA umsetzen möchte. Ich schreibe also zwei Topic und stelle beim Zusammenstellen zu einer Map fest, dass ich die in einem Inhaltsverzeichnis eigentlich unter eine Ober-Überschrift packen möchte. Was mache ich nun?

Es ist definitiv keine angebrachte Lösung ein Topic zu erstellen, das bis auf die Überschrift leer ist. Das ist zumindest meine Meinung. Daher bin ich auch der Suche nach einer anderen Lösung, die keinen unnötigen Topic-Overhead produziert.

Nun gibt es für Maps das Element <topichead>, das in der Map einen Eintrag anlegt, der nur als Titel fungiert und nicht auf ein Topic verlinkt werden muss. Aber momentan sieht das wohl so aus, dass im Inhaltsverzeichnis der Inhalt dieses Elements zwar vorkommt, aber im Textfluss es keine solche Überschrift gibt. Im PDF-Output hatte es sogar gar keine Auswirkung 🙁

Ich werde hier mal weiterrecherchieren. Mal wieder ein Problem, das ganz sicher sehr viele Redaktionen haben, wenn es um DITA geht, nur Lösungsmöglichkeiten findet man keine…

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.