Mit Potenzial zum Wachsen

Auch in einer kleinen Technischen Redak­tion mit nur einer oder zwei Personen kann es das Ziel sein, Texte zu modularisieren. Dafür ein eigenes Redaktionssystem einzuführen, lässt sich nicht immer durchsetzen. Neben den Kosten für das System ist die Zeit, in der die Texte ins System überführt werden sollen und noch keine neue Dokumentation publiziert werden kann, ein entscheidender Faktor.

Die Aufgabe, Bestandstexte formal zu zerschneiden und automatisiert in ein Redaktionssystem zu importieren, bedeutet, dass Inhalte nur mit einem neuen Werkzeug gepflegt werden. Mit der Einführung einer Modularisierungsmethode ergibt sich der Bedarf, die Inhalte zu überarbeiten, zu standardisieren, Terminologie anzuwenden und möglichst proprietäre Formatierung und Layoutgestaltung zu entfernen. Ein optimales Szenario für den Übergang wäre, dass während der Überarbeitung der Inhalte auch eine Kombination aus Dateien mit Bestandsdaten mit neuen, modular aufgebauten Inhalten möglich ist. Damit können jederzeit Handbücher oder auch Anleitungen ausgegeben werden, wenn man sie im Betriebsablauf benötigt. Auch nachträgliche Anpassungen und Ergänzungen „im laufenden Betrieb“ sollten leicht möglich sein.

Grundlegende Anforderungen

Skizzieren wir zunächst minimale Anforderungen, um modularisierte Technische Dokumentation umzusetzen.

• Module müssen inhaltlich so gestaltet sein, dass sie wiederverwendet werden können. Das Begrenzen des Inhalts auf eine Handlungsanweisung oder die Beschreibung eines Sachverhaltes hat sich bewährt, um Modularisierung kennenzulernen. Der Einsatz von Variablen für konkrete Produktbezeichnungen ist eine zusätzliche Hilfe.
• Das Layout einer Publikation soll angepasst werden können, ohne das Layout der Module verändern zu müssen.
• Mehrere Module sollen in einem Kapitel-Dokument zusammengefasst werden und im Textfluss ohne Seitenumbruch hintereinander stehen können.
• Für die genaue Klassifizierung eines Modul-Inhaltes werden Metadaten im Modul angegeben, die im Kapitel- Dokument ausgeblendet werden können.
• Bei neuen Anforderungen an Metadaten, Layout oder Formatierungen soll das System und alle bestehenden Inhalte leicht angepasst werden können.
• Wenn nicht sofort, aber eventuell etwas später, könnten die Inhalte Schritt für Schritt im selben System XML- basiert aufgebaut werden. Auch dabei ist die Kombination aus nicht strukturierten und strukturierten Modulen wünschenswert, um jederzeit publizieren zu können.
• Am Ende soll nicht nur PDF zur Druckausgabe entstehen, sondern auch Inhalte für mobile Apps oder auch Online-Hilfen, am besten barrierefrei.
• Dabei soll der Einsatz von Standard­software möglich sein, die leicht handhabbar ist, und die Ablage der Module und der daraus zusammengestellten Publikationen im Dateisystem organisiert werden. Funktionen, die von der Standardsoftware nicht angeboten werden, sollen sich durch Add-ons ergänzen lassen – je nach Bedarf.

Sucht man nach einem Werkzeug, das diese Forderungen erfüllen kann, dann stößt man auf Adobe FrameMaker – ein DTP-Werkzeug, das gleichzeitig bei Bedarf ein XML-Editor sein kann. Mit seinen beiden Funktionen „Dokumente in Dokumenten zu referenzieren“ und „Absätze durch Formate zu kennzeichnen und sie so ein- und auszublenden“ sind die wesentlichen Grundanforderungen realisierbar. Die ExtendScript-Schnittstelle bietet die Möglichkeit, die Software um spezielle Funktionen zu erweitern.

Im Folgenden wird beschrieben, wie sich Modularisierung konkret mit Adobe FrameMaker realisieren lässt. Die Beschreibung basiert auf meinen Erfahrungen aus über zehn Jahren praktischer Anwendung des Konzeptes in zahlreichen Technischen Redaktionen, vorrangig handelt es sich um kleinere.

In den nächsten Abschnitten folgen zunächst die Kernelemente, wenn man Modularisierung umsetzt und dazu Adobe FrameMaker verwendet.

Eine Ablagestruktur gestalten

Wie im großen so wird auch im kleinen Maßstab für die Ablage von Modulen (oder Topics) eine gut organisierte Ablagestruktur benötigt. Am einfachsten wird sie realisiert durch eine Verzeichnisstruktur im Dateisystem (Abb. 01). Der Aufbau kann sich beispielsweise an der Produktstruktur des Unternehmens orientieren. Mit der Verschachtelungstiefe der Ordner wächst die Spezialisierung der Inhalte, die in einem Ordner abgelegt sind.

Sollen zu einer Produktklasse, Produktgruppe oder einem Produkt Module in der Verzeichnisstruktur abgelegt werden, hat es sich bewährt, auf unterster Ebene noch Ordner mit dem Namen der üblichen Handbuchkapitel einzufügen. So können Module zum Thema „Montage“ leicht einem Dateiordner „Montage“ zugeordnet und wiedergefunden werden.

Drei Erfahrungen aus der Praxis:

1. Es ist sinnvoll, in der Ordnerstruktur die Namen mit eindeutigen Nummern zu ergänzen. Sollte es geschehen, dass der Ordner „Montage“ von Produkt A versehentlich mit der Maus verschoben wurde, kann die eindeutige Nummerierung helfen, den Ordner wieder an den ursprünglichen Platz zu bringen.

2. Es ist hilfreich, möglichst viele Ordner einzurichten; leere Ordner stören nicht, fehlende Ordner bewirken aber unerwünscht kreative Lösungen, die bald niemand mehr nachvollziehen kann.

3. Zur Handhabung ist es kein Problem, mehrere Tausend Ordner und darin mehrere Tausend Moduldateien zu verwalten. Wichtig ist, dass die Ablagestruktur als System intuitiv begreifbar ist und die Dateinamen nach ganz konkreten, einfachen Vereinbarungen vergeben werden. Um eine einheitliche und konsistent nummerierte Ablagestruktur zu erzeugen, steht ein Add-on zur Verfügung, das aus einer Konfigurationsdatei die Ordnernamen ausliest und in einem Augenblick mehrere Tausend korrekt benannte Verzeichnisse und Unterverzeichnisse erstellt. Muss die Ablagestruktur erweitert werden, wird die Konfigurationsdatei ergänzt und die Verzeichnisstruktur erweitert.

Abb. 01 Module werden einfach im Dateisystem abgelegt. Quelle Ute Mitschke

Die Formatreferenz erstellen

Möchte man das Layout von Modulen und Publikationen leicht ergänzen und anpassen, dann ist es notwendig, den Bedarf der Technischen Redaktion zu kanalisieren. Hintergrund: In einem FrameMaker-Dokument kann (nur) der Textflussinhalt von anderen Dokumenten im Textfluss referenziert werden, ähnlich wie beim Einfügen von Grafiken. Beim Importieren kann man sich entscheiden, ob die Formatdefinition des referenzierenden Dokuments auf gleichbenannte Absatzformate angewendet werden soll oder die Formatierung des referenzierten Moduls angezeigt wird.

Soll das Layout in einer Publikation angepasst werden, ohne in den Modulen die Formatierung ändern zu müssen, muss also die Formatierung der Kapiteldatei das Layout gewährleisten. Wird aber in einem Modul ein Format genutzt, das im Kapitel-Dokument nicht bekannt ist, dann lässt sich die Formatierung für diese Absätze nicht beeinflussen.

Die Konsequenz ist ein zentrales Dokument, in dem vollständig alle Formate erfasst, ergänzt und bearbeitet werden – das Dokument nennen wir „Formatreferenz“. Veränderte und ergänzte Formate für Absätze, Zeichen, Tabellen, Variablen, das Seitenlayout, Dokumenteinstellungen oder auch Objektstile können bei Änderungen mit Mausklick aus der Formatreferenz mit der Standardfunktion „Import von Formaten“ auf alle Module und alle Kapitel-Dokumente verteilt werden.

Die Metadaten anlegen

Werden im Textfluss der Module direkt am Beginn Absätze mit speziell benannten Formaten eingefügt, dann kann man dort Metadaten eintragen. In der Praxis haben sich folgende Minimalangaben bewährt:

• eine Kurzbeschreibung des Modulinhalts
• die Sprache, in der der Inhalt erstellt oder übersetzt wurde
• eine einfache Versionsnummer, mit der erkannt werden kann, ob eine übersetzte Fassung noch mit der aktuellen Modul-Fassung übereinstimmt
• eine Änderungshistorie

Wenn man in einem Modul kennzeichnen möchte, ob ein Dokument freigegeben ist oder überarbeitet wird, kann auch ein Metadatum für den Modul-Status ergänzt werden.

Weitere Metadaten sind firmenspezifisch und können etwa die Angabe einer Baureihe oder Produktklasse, die Angabe der Zielgruppe oder eine Kennzeichnung der Gültigkeit für eine Vertriebsregion mit anderer Zertifizierung enthalten.

Erfahrung aus der Praxis: Über die Versionsnummer kann man vergleichen, ob ein Modul in der Erstellungssprache inhaltlich mit den Übersetzungen des Moduls übereinstimmt. Damit kann eine Funktion zum Exportieren von zu übersetzenden Modulen gesteuert werden. Ein anderer Fall: Durch eine Baureihenklassifizierung können mithilfe eines Add-ons aus einer Publikation nicht zur Baureihe gehörende Module entfernt werden.

Wenn die Absätze für die Metadaten jeweils mit einzigartigen Formaten eingerichtet werden, ist es möglich, über die Metadaten aller Module ein Inhaltsverzeichnis zu generieren. Darin hat man alle Metadaten im Blick und erkennt, wo sie ergänzt oder korrigiert werden müssen.

Module administrieren

Neben der Möglichkeit, Dokumente zu erstellen, kann man mit Adobe FrameMaker auch eine Buchdatei erstellen. Darin lassen sich Dokumente referenzieren und gemeinsam behandeln. So kann man ein Suchen und Ersetzen (inklusive GREP-Funktionalität) über alle Dokumente des Buches ausführen.

Mit einem Add-on oder auch manuell lässt sich ein Buch erstellen, in dem die Dateiablagestruktur nachgebildet und alle Module referenziert werden können. Dieses Buch nennen wir Modul-Administrationsbuch (Abb. 02). Es kann beim Erstellen von Dokumenten in der Programmoberfläche von FrameMaker geöffnet sein. Damit muss man für den Überblick über die vorhandenen Module und deren Dateinamen oder Inhalte nicht extra im Dateiexplorer nachsehen. Im Modul-Administrationsbuch lässt sich auch das Inhaltsverzeichnis über alle Metadaten generieren, um nur diese über alle Module schnell zu analysieren. Für das Erstellen eines Modul-Administrationsbuchs gibt es ein Add-on, das auch für alle anderen Dokumentablagestrukturen eingesetzt werden kann.

Abb. 02 Das Modul-Administrationsbuch bildet die Ablagestruktur nach. Quelle Ute Mitschke

In Publikation zusammenfügen

Beginnen Sie damit, den Inhalt aus einem in jeder Publikation genutzten Kapitel zu modularisieren. Auf Basis des Modul-Templates erstellen Sie eine neue Datei, pflegen die Metadaten und übertragen den Inhalt und formatieren diesen mit den vereinbarten Absatz-, Zeichen- oder auch Tabellenformaten. Speichern Sie die Moduldatei im passenden Ordner und vergeben Sie einen Dateinamen nach den vorher festgelegten Dateinamenskonventionen. Ein dreiteiliger Dateiname hat sich bewährt: Er beginnt mit einem zweistelligen Kürzel, das die enthaltene Information beschreibt, beispielsweise HA für Handlungsanweisung, SH für Sicherheitshinweis, TD für technische Daten und Ähnliches. Dann wird eine kurze Inhaltsangabe ergänzt. Bedenken Sie, dass der Moduldateiname in der Ablagestruktur zusammen mit der Pfadangabe nicht mehr als 250 Zeichen umfasst.

Erstellen Sie gleichzeitig aus dem Publikationstemplate ein neues Kapitel-Dokument und importieren/referenzieren Sie darin in der korrekten Reihenfolge die Textflüsse der fertigen Module. Vergleichen Sie abschließend das neu erstellte Kapitel-Dokument mit dem Bestandsdokument, um sicherzustellen, dass kein Inhalt vergessen wurde. Fehlende Inhalte lassen sich nachträglich schwer erkennen. Das Kapitel-Dokument fügen Sie nach Wunsch in eine Buchdatei ein, in der alle Kapitel, Deckblatt, Rückseite, Inhaltsverzeichnis und Index der Publikation gemeinsam verwaltet werden.

Auf Basis einer Buchdatei mit den enthaltenen Kapitel-Dokumenten können Sie durch Kopie der Dateien Abwandlungen für andere Publikationen erstellen.

Erfahrung aus der Praxis: Wird nur ein einziges Template für Module und Publikationen genutzt, kann dieses mit allen Format­informationen eine beachtliche Dateigröße erreichen. Da in Modulen aber nie das Seitenlayout benötigt wird, können in einem speziellen Modul-Template alle benutzerspezifischen Vorgabeseiten (Masterpages) und auch die Referenzseiten zur Konfiguration von Inhaltsverzeichnis und Index entfernt werden. Stattdessen können im Modul-Template die Metadatenabsätze bereits eingefügt, mit Inhalten vorbelegt und diese Absätze als „Bedingter Text“ mit dem Bedingungsformat für Metadaten formatiert werden.

Das Publikations-Template dagegen enthält keine Metadatenabsätze und benötigt alle Vorgabe- und Referenzseiten.

Übersetzungsprozess festlegen

Wenn in Kapitel-Dokumenten Text niemals direkt in Absätzen eingetragen wird, sondern der Inhalt ausschließlich aus Modulen referenziert wird, dann ist gewährleistet, dass nur nicht vorhandene oder nicht aktuell übersetzte Module zur Übersetzung ausgewählt werden müssen.

Es wird eine konkrete Publikation betrachtet und alle Kapitel-Dokumente des Buches analysiert. Dabei werden die referenzierten Module (Texteinschübe) erkannt und deren Ordner- und Dateinamen ermittelt. In der identisch aufgebauten Verzeichnisstruktur für die Zielsprache der Übersetzung wird dann geprüft, ob das Modul in der korrekten Version enthalten ist. Trifft das nicht zu, wird das Modul in einen Übersetzungsprojektordner kopiert. Wurden alle Dokumente der Publikation vollständig analysiert, können die Module übersetzt und anschließend mit identischem Dateinamen in den identischen Ordner der Zielsprache kopiert werden.

Die übersetzte Publikation entsteht durch Kopieren des Ordners mit Buch- und Kapitel-Dateien an dieselbe Position in der Ablagestruktur der Zielsprache. Dadurch, dass die Module in den Kapiteln mit relativen Pfadangaben referenziert werden, werden beim Öffnen der Kapiteldateien die übersetzten Module referenziert und die Kapitel erscheinen vollständig übersetzt.

Zuletzt müssen nur noch die sprachspezifischen Eigenschaften der Formate in die Kapitel importiert werden und die übersetzte Publikation ist fertig. Werden sprachabhängige Abbildungen benötigt, sollten deren Dateinamen auch in jeder Sprache identisch sein, damit die Referenz auf die Grafiken sich auch automatisch aktualisiert.

Für den Export von Modulen zur Übersetzung und den Import von Modulen nach der Übersetzung in die Ablagestruktur stehen Add-ons zur Verfügung, die diese Aufgaben automatisieren.

Basisformat der Dateien wählen

Mit FrameMaker kann man in derselben Programmoberfläche native Dokumente und FrameMaker-Dokumente mit XML-Struktur erstellen. Es ist möglich, jede beliebige eigene Elementstruktur zu implementieren oder bereits mitgelieferte Strukturen wie DITA, xhtml oder xDocBook zu nutzen.

Das Arbeiten mit XML-basierten, so genannten strukturierten Dokumenten bietet Vorteile gegenüber nativen Dokumenten. Der wesentliche Vorteil besteht darin, dass Absätze gleichzeitig einem Element in der Struktur entsprechen und je nach Kontext, in dem sie vorkommen, ein konkretes Format zugewiesen wird. So ist es möglich, dass Module, mit Titel-Elementen an beliebiger Position in der Elementstruktur referenziert, immer die korrekte Titelformatierung und damit auch Nummerierung erhalten. In nativ aufgebauten Modulen werden den Titelabsätzen konkrete Formate zugewiesen, die im Kapitel-Dokument unverändert bleiben.

Publikation ausgeben

FrameMaker kann mit der Standardfunktion „Veröffentlichen“ eine Publikation in verschiedene Ausgabeformate konvertieren. Werden dabei ein paar grundlegende Einstellungen vorgenommen, können die automatisch erzeugten Ausgaben auch barrierefrei sein.

Alt und Neu kombinieren

Wir haben im Prozess zwei Übergangsphasen, für die jeweils die gleichen Möglichkeiten zur Verfügung stehen:

• Die Kombination von komplett erstellten Kapiteln ohne Module mit Kapiteln, die ausschließlich Module referenzieren in einem Buch für eine konkrete Publikation.
• Die Kombination von Kapiteln mit nur nativen Modulen und Kapiteln mit ausschließlich strukturierten Modulen.

In beiden Fällen ist die Grenze für den Wandel das Kapitel-Dokument. Doch die Möglichkeit, unterschiedliche Entwicklungsstände gemeinsam zu publizieren, ist der Schlüssel für eine „sanfte“ Einführung der Modularisierungsmethode in der Technischen Redaktion. Sie lässt Raum für das Tagesgeschäft und erlaubt dennoch eine ständige Weiterentwicklung entsprechend den vorhandenen Möglichkeiten.

Aktuellen Stand einfrieren

In den einmal zusammengestellten Kapitel-Dokumenten werden „aktive“ Module eingesetzt. Wird ein Modul geändert, ändert sich automatisch auch der Inhalt in allen Kapitel-Dokumenten, die das Modul referenzieren. Soll eine konkrete Publikation im veröffentlichten Zustand aufbewahrt werden, muss die Publikation „eingefroren“ werden. Dazu werden alle Module aus dem Ordner mit Buch- und Kapiteldateien kopiert und in die Kapiteldateien inklusive der referenzierten Grafiken eingebettet. Damit erhält man den unveränderlichen Inhalt in einem dennoch nachträglich kopierbaren Datenformat der Erstellungssoftware.

Erfahrungen sammeln

Wendet man in Adobe FrameMaker konsequent das Konzept der Modularisierung an und hält sich an alle Regeln, kann man die gesamte Technische Dokumentation modular aufbauen, stückweise Bestandsdaten überarbeiten, die Inhalte mit XML-Struktur ergänzen und erste Erfahrungen mit der Modularisierungsgröße und den passenden Metadaten machen. Das System kann diese Anpassungen skalierbar bewältigen. Und sollte es passieren, dass die Anzahl an Modulen zu groß geworden ist, um sie in einer Dateiablage zu handhaben, oder werden andere Funktionen benötigt, wie der Zugriff auf verschiedene Versionen eines Moduls, kann ein Redaktionssystem eingeführt werden. Dann hat die Technische Redaktion bereits viele Erfahrungen im Umgang mit Modularisierung gemacht und weiß, ein Redaktionssystem richtig zu beurteilen und einzusetzen.