Topic-basiertes Schreiben mit MadCap Flare

Äh, Topics? Im Beitrag Topics: Informationshäppchen hirngerecht servieren wurde bereits beschrieben, dass Topics kleine Einheiten in der Technischen Dokumentation sind, mit denen dem Leser (und auch dem Redakteur) die Erfassung situativ relevanter Informationen erleichtert werden soll. Wie aber macht man das? Ganz einfach: Man stellt den zu beschreibenden Sachverhalt auf den Kopf und schüttelt so lange, bis nichts mehr herausfällt. Dann dreht man es wieder um und beginnt mit der Erfassung. Alles klar?

Wie bei den Häppchen spielt es auch für Topics zunächst keine Rolle, wo sie später serviert werden. Ob es bei der Ausgabe um ein gedrucktes Dokument, eine Onlinehilfe oder eine PDF, einen kontextsensitiven Hilfetext auf dem Bildschirm oder ein e-Learning-Dokument geht, hat mit der Information selbst nichts zu tun. Entsprechend muss sie so konzipiert werden, dass sie ohne Nacharbeit überall eingesetzt werden kann.

Position ist Bedeutung

Durch die Position der Topics bestimmt sich meist auch ihre Bedeutung. Allerdings muss der Sachverhalt dann auch neutral beschrieben werden: die Information muss so abgefasst sein, dass jeglicher Bezug auf eine bestimmte Position vermieden wird.

Meist wird dies in Onlinehilfe-Systemen bereits umgesetzt – sofern sie modular angelegt sind. In der klassischen Technischen Dokumentation im Maschinenbau ist das noch nicht so weit entwickelt, da die meisten Prozesse aus physikalischen Gegebenheiten linear sind und der Redakteur dadurch verleitet ist, entsprechend unidirektional zu denken. Die Schwierigkeit ist daher, universell einsetzbare Topics zu identifizieren und zu bestimmen, was sie beinhalten werden – und die Bedeutungszuweisung dem Kontext zu überlassen. Man braucht also eine Struktur. Wie man das machen kann, steht auch im Beitrag Anlagendokumentationen planen und steuern: Erst denken, dann schreiben).

Struktur und Prozess

Zwei Schritte weiter. Wir stellen uns vor, diese Struktur ist vorhanden, alle Topics sind bestimmt. Für die Umsetzung nehmen wir das Programm MadCap Flare, selbst wenn wir nicht für eine Online-Ausgabe schreiben. (Natürlich eignet sich dazu jedes Programm, mit dem Inhalte modular erfasst und zusammengesetzt werden können.)

Konzept

Wer schon einmal mit Robohelp oder ähnlichen Editoren zum Erzeugen einer Onlinehilfe gearbeitet hat, kommt mit der Benutzung des Programms zwar schneller zurecht, muss aber darauf achten, das Programm nicht in die Schublade „Softwaredokumentation“ zu werfen. Denn Flare kann als Grundlage für zahlreiche Publikationsmedien dienen – einschließlich Druck.

Dazu bietet Flare Funktionen, wie sie vor allem in der technischen Dokumentation wichtig sind. Dort zählt die Konsistenz in Layout, Stil und Aufbau zu den wichtigsten Zielen. Daher werden in Flare (wie in anderen HTML-Editoren auch) alle Topics nach der Erstellung in ein Template geladen, das das spätere Aussehen („Look & Feel“) der Ausgabe definiert. Das bedeutet umgekehrt auch, dass alle Topics unabhängig von ihrem späteren Aussehen erfasst werden müssen. Sie werden als einfache HTML-Dateien abgelegt und erst bei der Ausgabe abhängig vom Ausgabemedium mit Formatvorlagen, Navigationselementen, Suchfunktionen, Index, Seitenzahlen usw. versehen. Das Layout beim Erfassen der Inhalte dient daher nur  der optischen Kontrolle, ist aber nicht identisch zur späteren Ausgabe. Diese spielt nämlich für die Erfassung der Inhalte keine Rolle.

Erst importieren oder doch lieber erst aufräumen?

Flare ist bei der Datenübernahme äußerst tolerant: Bereits bestehende Inhalte aus den unterschiedlichsten Quellen lassen sich importieren und dann innerhalb des Flare-Verzeichnisbaums ablegen. An dieser Stelle greifen allerdings die Besonderheiten der Auszeichnungssprachen wie HTML: alle Informationen, also auch Grafiken und Bilder müssen innerhalb eines Stammverzeichnisses liegen, da eine Auszeichnungssprache nur aus Text besteht und andere Dateien wie Filme oder eben Bilder referenziert. Was nicht erreicht werden kann, weil es auf einem anderen Laufwerk liegt, das gerade nicht zur Verfügung steht, wird auch nicht angezeigt.

Allerdings ist der direkte Import nicht unbedingt der ideale Weg, denn die importierten Dokumente könnten mitunter nicht themenzentriert erstellt worden sein, sondern eben „klassisch“. Da stehen dann Funktionsbeschreibungen neben Warnhinweisen oder Bedienung und Wartung wird munter gemischt. Daher ist es möglicherweise effizienter, vor dem Import nochmals Hand an den Inhalt anzulegen und die Datenquellen aufzuräumen oder so zu „zerschneiden“, dass wir die Inhalte nur bruchstückweise übernehmen, beispielsweise, indem wir vor dem Import viele kleine Topics mit einem Editor anlegen.

Daher brauchen wir zunächst eine Liste der Topics, die wir uns anlegen, um die Inhalte später dort zu erfassen. Diese Liste erfordert eine gewisse Planung (dazu auch Antizipatives Schreiben: Weiter als der eigene Horizont).

Anlegen

Gehen wir jetzt davon aus, dass diese Gliederung existiert und wir also eine Vorstellung davon haben, welche Topics benötigt werden, und wie wir sie gliedern können.

Auf geht’s:

1. Flare starten und ein neues Projekt anlegen. Am besten gleich ein leeres Projekt anlegen, denn wir haben ja schon eine Struktur.
2. Projektvorlage auswählen. Diese lässt sich später anpassen und erweitern, legt aber schon mal die benötigten Verzeichnisse und das primäre Ausgabeformat an. Das darf auch PDF sein, für das MadCap mehrere Vorlagen anbietet.
   Die Möglichkeit, ein System aus HTML-Dokumenten wie eine Internetseite auszubauen und dann als gedruckte Dokumentation zu liefern, ist eine der Besonderheiten. Der Vorteil davon ist, dass es zwar recht einfach ist, von einer Internetseite ein umfangreiches PDF-Dokument zu produzieren, umgekehrt aber sehr mühsam.

Flare hat uns mit der Auswahl der Vorlage die erste Arbeit schon abgenommen und Ordner angelegt, in die sinnvollerweise die Topics beziehungsweise Bilder gelegt werden. Da diese Ordner von Flare verwaltet werden, muss man sich jetzt nur angewöhnen, das gesamte Konstrukt als eine einzige Datei zu betrachten. Das Umbenennen oder Verschieben von Ordnern und Dateien sollten wir daher immer in Flare durchführen – und nicht im Dateisystem.

Nun kommt die Arbeit, für die wir Redakteure bezahlt werden: Inhalte erfassen und zu Topics bündeln.

Erfassen

Das Erfassen von Inhalten in der Technischen Dokumentation ist reines Handwerk. Also erstellen wir in Flare zunächst analog zu unseren Topics eigene Seiten in den jeweiligen Verzeichnissen in Flare.

Sobald alle Topics angelegt sind (zunächst unabhängig von ihrer geplanten Hierarchie), beginnen wir mit dem Füllen. Es spielt überhaupt keine Rolle, mit welchem Topic wir beginnen, denn alle haben ja später ihren Platz und damit auch ihre Bedeutung.

Bei der Erfassung der Inhalte können wir dann eigentlich so vorgehen, wie aus einem Texteditor bekannt: Listen, Tabellen, Grafiken und was sonst für eine verständliche Übermittlung der Informationen notwendig sein kann. Dennoch steht hinter jedem Inhaltsbaustein die Forderung, so genau wie nötig, aber so allgemeingültig wie möglich zu schreiben.

Wie es sich für einen guten Editor gehört, können die Grafiken, Bilder und Filme natürlich direkt mit einem externen Programm bearbeitet werden. Gerade wer mit dem Programm FrameMaker vertraut ist, findet sich hier sehr schnell zurecht: Querverweise werden genauso angelegt, es gibt Bedingungsformate und Variablen, die für die Publikation zum Tragen kommen können.  Sogar Texteinschübe, also mehrfach verwendbare Textbausteine, sind möglich: in Flare heißen sie „Snippets“ und werden wie auch Bilder im Ordner „Resourcen“ abgelegt und dort angepasst. Sobald sie geändert werden, werden diese Änderungen in allen Topics nachgezogen.

Selbst der aus der Arbeit mit strukturierten Dokumenten in FrameMaker bekannte „Strukturbaum“ fehlt nicht: Die Elemente werden in Form kleiner Rechtecke am linken Bildrand dargestellt. Auch mit ihnen lässt sich arbeiten, sobald man sich mit den Grundzügen der Auszeichnungssprachen vertraut gemacht hat.

Die „Dos“ und die „Don’ts“

Aber jetzt mal ganz konkret: Worauf sollte man achten beim Schreiben? Nachfolgend eine kleine Hilfe zu den „Dos“ und den „Dont’s“, also so, wie man es gerne beim Schreiben passiert und so, wie es sich optimieren lässt.

• Konkrete Bezüge zum Gegenstand soweit wie möglich vermeiden, so allgemein wie nur möglich schreiben.
• Topics nicht ineinander verschachteln (Transklusion), sondern aufeinander verweisen (Hyperlinking). Verweise sind einfacher zu verwalten als Textbausteine.

Dazu schütteln wir zunächst alles heraus. Und dann ergänzen wir nach reiflicher Überlegung nur das Notwendigste.

Beispiel: In einem Topic zum Thema „Bauteil in einem Gehäuse austauschen“ (oder einsetzen bzw. herausnehmen) taucht der folgende Satz auf: Nehmen Sie den Deckel und den Dichtring mit Hilfe eines Schraubendrehers an den vier Befestigungsschrauben ab. Dieser Satz besitzt – unabhängig davon, ob die personalisierte Form gewählt werden soll oder muss – die Kernaussage Nehmen Sie den Deckel ab (oder eben noch kürzer Deckel abnehmen). Handelt es sich um eine Tätigkeit, die eine Fachkraft durchführen soll, würde dies genügen. Warum?

• Dass der Mensch bei einem verschraubten Deckel zum Werkzeug greifen wird, ist ja anzunehmen. Eleganterweise könnte man dem gesamten Handlungspaket noch das benötigte Werkzeug voranstellen (Hilfsmittel: Schraubendreher). Aber auch das nur, wenn es keinen Deckel gibt, der mit einem Schraubenschlüssel geöffnet werden muss, denn sonst ist die Beschreibung nicht mehr allgemeingültig.
• Dass es sich um Befestigungsschrauben handelt ist klar, das muss man nicht eigens dazu schreiben.
• Falls der Dichtring am Deckel befestigt ist, wird er sowieso mit dem Deckel abgenommen, dann muss das auch nicht erwähnt werden. (Falls der Dichtring ausgetauscht werden soll, machen wir daraus ein eigenes Topic.)
• Darüber hinaus ist die Angabe zur Anzahl der Schrauben überflüssig, denn wenn nicht alle Schrauben gelöst wurden, kann der Deckel ja nicht abgenommen werden.
• Sollte es jedoch mehrere Deckel geben, die vielleicht auch im Zusammenhang mit diesem Handlungspaket abgenommen werden müssen, benötigen wir eine grafische Darstellung, mit einer Nummerierung, die wir natürlich im Handlungsschritt ergänzen müssen: Deckel (1) abnehmen.

Der Satz ist jetzt kürzer und auch wesentlich billiger in der Übersetzung, denn dort können Zahlen automatisch übersetzt werden. Kommt dieser Satz in mehreren Topics vor mit unterschiedlichen Zahlen, erkennt das Übersetzungsprogramm, dass es sich um einen identischen Satz handelt und tauscht die Zahlen automatisch aus. Das spart viel Zeit und Geld.

Diese gedanklichen Prozesse, die uns jetzt so schön den Satz haben kürzen lassen, müssen wir allerdings auf jeden Satz anwenden. Eine Sysiphosaufgabe, vor allem wenn ein bereits bestehender Dokumentenbestand nachgearbeitet werden müsste. Hier ist der Konjunktiv beabsichtigt, denn natürlich lässt sich dies nicht für jeden Satz in einem Rutsch erledigen. Allerdings unterstützt uns an dieser Stelle die Arbeit mit Topics: Einmal bearbeitet, kann dieses Topic ja als abgeschlossen betrachtet werden und es wird nur noch darauf verwiesen. Die Arbeit macht man also nur einmal.

Fazit

Der einzig wesentliche Unterschied zu einem Programm wie FrameMaker sind somit die Topics, die durch ihre Flexibilität und neutrales Format später für eine Vielzahl unterschiedlicher Ausgabeformate geeignet sind: ePub genauso wie Word, FrameMaker oder Onlinehilfe. Dem so genannten „Singlesource-Publishing“ kommt man mit MadCap Flare sehr nahe – sofern die Inhalte Topic-basiert erfasst wurden.

Related Images: