MadCap Analyzer: Gabelstapler für Onlinehilfen

Bevor Sie weiterlesen: Analyzer ist eine Ergänzung zu MadCap Flare. Ohne Letzteres nutzt Ihnen der Analyzer wenig. Mit Flare allerdings ist das der Gabelstapler für die schweren Sachen.

Über die Vorzüge von Flare für das „Single-source-multichannel-publishing“ muss ich an dieser Stelle kein Wort verlieren – das habe ich an anderer Stelle schon mehrmals (siehe Onlinedokumentation mit Flare 12: Any color you like und Topic-basiertes Schreiben mit MadCap Flare). Voraussetzung ist daher, dass Sie bereits begonnen oder wie ich – quasi mit verschärften Bedingungen – ein komplettes Robohelp-System übernommen haben. Wie auch immer: diese Informationen stammen aus unterschiedlichen Quellen von unterschiedlichen Autoren zu unterschiedlichen Zeitpunkten. Single-source Publishing bedeutet ja mitnichten, dass die Informationen, die aus einer Quelle kommen, auch von einer Quelle stammen. Im Gegenteil, es sammelt sich trotz „guten Willens und steten Bemühens“ im Laufe der Jahre doch eine Menge an „Gremlins“ an:

• Verwaiste Links, die auf nicht mehr vorhandene Texte oder Bilder verweisen
• Sonderzeichen im Text (vom Kopieren und Anpassen aus anderen Programmen wie Word, die sachfremde Abteilungen wie Vertrieb oder Marketing liefern), die nicht Unicode-konform sind oder völlig anders belegt (z.B. englische Anführungszeichen in deutschen texten)
• Texte und Sätze, die sehr ähnlich klingen und eigentlich vereinheitlicht werden müssten („Lösen Sie die Schrauben und nehmen Sie den Deckel ab.“ oder „Lösen Sie die Schrauben und öffnen Sie den Deckel.“)
• Textformate, die nicht identisch zugewiesen wurden
• Wiederkehrende Formulierungen, die man eigentlich als „Fragment“ (ST4) oder „Texteinschub“ (FrameMaker) oder „Snippet“ (InDesign bzw. Flare) führen könnte, damit sie nur an einer Stelle geändert werden müssen und in 25 Textpassagen aktualisiert werden

Gerade wiederkehrende Formulierungen sind in der Software-Dokumentation besonders häufig, denn modulare Texte verlangen nach einer konsistenten Benutzerführung: Tätigkeiten wie „Übernehmen“ und „Speichern“ werden häufig vom Benutzer verlangt und tauchen daher auch entsprechend häufig in der Dokumentation auf (sonst ist die Handlung nicht abgeschlossen). Diese nun jedesmal neu zu schreiben öffnet den Abweichungen Tür und Tor – vor allem, wenn die beschreibenen Tätigkeiten erst im Lauf von Jahren dazu kommen („Wie hatte ich das letztes Jahr beschrieben?“).

Wenn man das von vornherein weiß, lassen sich die entsprechenden Snippets in Flare prima anlegen und einsetzen. ((Beispielsweise für Sicherheitshinweise.))

Was aber, wenn die Software „lebt“ und neue Funktionen dazu kommen und alte angepasst werden? Aus mehreren hundert Topics die zu finden, die eines Snippets würdig sind, ist eine sehr zeitaufwändige Arbeit.

Hier hilft der Analyzer

Um den Analyzer zum Arbeiten zu bewegen, startet man das Programm entweder direkt und öffnet dann das Flare-Projekt, oder – einfacher – man startet den Analyzer direkt aus dem geöffneten Projekt heraus.

Der Vorteil einer „Stand-alone-Lösung“ liegt auf der Hand: Die Texte können von einem Autor kontrolliert werden („Vier-Augen-Prinzip“), der einen technischen Blick auf die Dokumente hat. Der Analyzer untersucht nämlich die gesamten Dokumente auf verwaiste Links, defekte Links, benutzte und nicht benutzte Stile (CSS-Formate), und auch auf mögliche Strukturprobleme wie mehrere Überschriften in einem Topic ((Das ist in einem HTML möglich, widerspricht aber der modularen Logik, nach der ein Topic eben nur eine Überschrift haben darf – hier schlägt die doch sehr lockere Definition des HTML zu.)).

Nach der Analyse des Projekts zeigt der Analyzer eine Übersicht zu allen Fragen, die ihm aufgefallen sind. An dieser Stelle soll es aber nur um die Snippets gehen.

Snippets erstellen und einsetzen

Wir öffnen jetzt in der Liste die Vorschläge, die Analyzer zu möglichen Wiederverwendungen macht. Nur zwei? OK. Das sieht ja nun nicht schlimm aus. ((Ich liebe diese Funktion, daher suche ich häufig nach Möglichkeiten, mir die Arbeit zu erleichtern nach dem Prinzip des „Write-once-publish-everywhere“.)) Ein Doppelklick auf einen Eintrag öffnet das Topic und hebt die fragliche Stelle hervor.

Mit der rechten Maustaste auf die Absatzmarkierung klicken und „Create Snippet…“ wählen.

Analyzer verlangt nach einem Namen für das Snippet und zeigt es ohne Formatierung an. Wenn man „Replace Source Content with the New Snippet“ aktiviert, wird das gewählte Textstück ausgetauscht: für den Leser sieht das gleich aus, in Flare wird dieser Absatz aber in einem Ordner „Snippets“ abgelegt und hier neu verlinkt.

Der nächste Text hat aber noch kein Snippet. Daher kopieren wir das eingefügte Snippet und öffnen das folgende Topic. Und jetzt wird einfach markiert und eingefügt. Fertig.

Nach dem Speichern wird der Absatz aus einer einzigen Quelle bestückt. Sobald sich (in diesem Beispiel) die IP-Adresse ändert, wird sie automatisch überall angepasst. So wie es sich gehört für eine gute Dokumentation.

Wieder einmal „Suchen & Ersetzen“ gespart. Das ist nämlich sowas von letztes Jahrtausend.

Bildquelle: 179lengyea.blogspot.com