Technische Dokumentation: Schlank durchs Jahr

Ja, auch Technische Dokumentationen besitzen eine gewisse Eitelkeit und wollen ganz gerne eine sportlich-schlanke Figur abgeben. Denn das verleitet nicht nur die Nutzer zum Hinschauen, sondern nutzt auch dem Ziel der Informationsvermittlung.

Jeder Redakteur, der eine Dokumentation über Jahre hinweg betreut und zahlreiche Änderungen, Aktualisierungen und Ergänzungen daran durchgeführt hat, weiß um das Problem: Auch die durchdachteste und disziplinierteste Arbeitsweise verhindert nicht, dass die Dokumentation Speck ansetzt: Hier mal ein hochauflösendes Bild dazu, dort eine Variante oder Option eingefügt, vielleicht noch im Zeitdruck die Begrifflichkeit etwas nachlässiger angegangen und entsprechend Redundanz erzeugt – und schon werden aus 5 MB auf einmal 10 MB und aus „mal schnell ändern“ werden zwei Tage.

Nun kann es nicht das Ziel jeder Dokumentation sein, einen beneidenswerten „Waschbrettbauch“ zur Schau zu stellen, denn der Aufwand dazu ist enorm (wie im Alltag halt auch) – und erfordert vom Technischen Redakteur schier übermenschliche Kräfte und Disziplin, sich gegen die wohlmeinenden Wünsche der SMEs zur Wehr zu setzen und keiner Verlockung nachzugeben, vielleicht nicht doch noch eine Tabelle oder Liste oder neue Bilder einzubauen. ((Gemeint sind Bilder und Tabellen, die meist aus ganz anderen Gründen erstellt wurden und in der Dokumentation aus Bequemlichkeit recycelt werden. Sie passen meist nicht zur Intention der Kundendokumentation.))

Trotz der Vorahnung, dass jeder Zusatz nur sehr schwer nachträglich wieder zu entfernen ist, lässt man halt dann doch mal Fünfe grade sein und fügt sich den Ideen und Vorschlägen, die sich im Laufe der Jahre so ansammeln. ((Bei Selbstständigen kommt noch dazu, dass der Aufwand, der getrieben werden muss, um eine Dokumentation schlank zu halten, oft nicht honoriert wird: man sieht es nämlich nicht.))

Das böse Erwachen kommt erst viel später:

• Hyperlinks und Querverweise, die ins Leere führen
• Bilder und Screenshots, von denen Jahre später kein Mensch weiß, wozu sie überhaupt da sind und sowieso nur eine veralteten Stand abbilden
• Ladezeiten, die jedem Leser mit einem durchschnittlichen Tarif den Schweiß auf die Stirn treiben
• Anleitungen in Romanstärke, bei denen alleine die Einleitung (mit freundlichem Gruß aus der Marketingabteilung) nicht unter 10 Seiten und 12 Bildern daher kommt
• explodierende Kosten bei der Übersetzung und Lokalisierung

Ergo: So wie sich eine ungesunde Lebensführung erst viele Jahre später bemerkbar macht, legt sich die Dokumentation im Laufe weniger Jahre ein „Hüftgold“ zu, das nur mit einem enormen Aufwand wieder einigermaßen in Form zu bekommen ist.

Aber genug der Analogien…

Um dauerhaft eine Dokumentation auf Kurs zu halten, benötigt man eigentlich nur zwei Dinge: eine Vorstellung vom erreichbaren Ziel – und das richtige Werkzeug.

Flare und Analyzer

Meine bevorzugte Kombination als Nutzer von MadCap Flare ist der zusätzliche Analyzer ((Ich habe ihn hier schon beschreiben: MadCap Analyzer: Gabelstapler für Onlinehilfen.)). Dadurch, dass in Flare die Texte als Topics angelegt sind, finden sich redundante Stellen zwar schnell, aber mit Analyzer geht es noch schneller: Analyzer schlägt nach dem Durchlauf vor, identische Formulierungen als Snippets anzulegen. Damit werden einmal erstellte Textbausteine an mehreren Stellen wiederverwendbar eingesetzt. Das kann man zwar machen – man kann sich aber auch die Frage stellen, ob ein mehrfach verwendeter Text nicht möglicherweise auf Redundanz hindeutet (Ausnahme: Sicherheitshinweise). Die Dokumentation ist ja keine Rumpelkammer – und jede Information, die mehrfach vorliegt, führt nicht nur zu Verwirrung, sondern auch zu mehr Pflege.

Eine hervorragende Funktion ist die Suche nach nicht benutzten (aka referenzierten) Dateien. Nicht referenzierte Bilder und Dateien, auf deren Inhalt nirgendwo verwiesen wird, sind überflüssig. ((Flare liefert bei der Publikation zwar nur die Bilder und Topics, die auch wirklich referenziert sind, aber die anderen bleiben trotzdem als „Leichen“ im Projektordner und treiben den Pflegeaufwand nach oben.)).

Nach der Analyse liefert das Programm alle möglichen Schwachstellen, die sich nun ganz einfach beheben lassen. Um den Aufwand gering zu halten, fängt man am Besten damit an, die fehlenden Dateien einzubauen, die das Programm moniert. Danach löscht man die nicht benutzten Dateien.

Adobe InDesign

Es geht teilweise aber auch mit InDesign: Die Funktion, Dateien für den Druck bereitzustellen, ist zwar angesichts der zunehmenden Online-Publikationen etwas merkwürdig, soll sie doch eine fehlerfreie Druckausgabe sicherstellen – man kann sie aber auch anders nutzen. Denn auch für die Druckerei ist es wenig hilfreich, Bilder zu erhalten, die nicht gedruckt werden. Die Bereitstellung als „Package“-Datei eines Buches zieht deswegen nur die Bilder, Schriften und sonstigen informationen zusammen, die auch referenziert werden. Diese werden dann in einen neuen Ordner gepackt und ggf. die Verweise angepasst. Dadurch entsteht eine in sich geschlossene Kopie des Originals, dessen Informaionen möglicherweise irgendwo im Dateisystem versteckt sind.

Danach kann man diese Pakete weiterverwenden und behält dadurch nur die tatsächlich benutzten Daten. ((Erfahrungsgemäß ist der Grafikordner immer der „dickste“.)) Allerdings funktioniert das nur für Bilder und Grafiken (und Zeichensätze), denn InDesign analysiert den Inhalt nicht auf Redundanzen. Dafür ist das Programm ja auch nicht gemacht …

Warnung

Ein Hinweis bevor Sie jetzt mutig den Frühjahrsputz angehen: Ohne regelmäßige Backups sollten Sie sich nicht ans Löschen machen. Sowas kann böse enden.

Sollten sie noch andere Möglichkeiten kennen, wie man die Dokumentation schlank halten kann: Nur zu!