MadCap Flare und Atlassian Confluence: das Powercouple

Festhalten, es wird nerdig. Denn es geht um Prozesse in der Technikredaktion – nicht, dass man auch als Außenseiter immer dazulernen kann, aber man sollte schon etwas Erfahrung mit der effizienten Produktion didaktischer Inhalte besitzen.

You have been warned.

Ich habe mich an anderer Stelle schon über die Vorzüge des topic-basierten Erfassens technischer Inhalte ausgebreitet (Topics: Informationshäppchen hirngerecht servieren), das möchte ich hier überspringen. Ein recht gut geeignetes Tool für diesen Zweck ist MadCap Flare, das eine topic-basierte Arbeitsweise erlaubt, ohne eine Datenbank zugrunde zu legen, wie es beispielsweise Redaktionssysteme machen, die – zu Recht – ein Vielfaches kosten.

Confluence

Das andere Tool, um das es hier gehen soll, ist eigentlich ein Wiki: Confluence von der Firma Atlassian.¹ Ein Wiki ist normalerweise nicht unbedingt dazu geeignet, Informationen so zu strukturieren, wie man sie für Topics benötigt, da man die Informationen einfach hineinschütten und dann miteinander verknüpfen kann, ohne sich an bestimmte Regeln zum Aufbau oder der Auffindbarkeit zu halten: Man legt einfach eine neue Seite an und klopft den Inhalt hinein, nagelt ein paar Fotos dazu und fertig ist die Kiste.

Da Confluence über exquisite Filter- und Suchfunktionen verfügt, ist das Wiederauffinden der Seiten und Inhalte kein Problem. Darüber hinaus bietet die App auch eine Kommentarfunktion, eine Kollaborationsfunktion und eine Anmerkungsfunktion an – also alles, was man zur Erfassung und Überarbeitung der Inhalte benötigt. Wer sich ausschließlich online bewegt und Zugriff auf die Seiten hat, kann natürlich auch mit Mobilgeräten darauf zugreifen und die Inhalte aktualisieren. Die Änderungen werden automatisch protokolliert. Dadurch kann man alte Inhalte vergleichen und gegebenenfalls wiederherstellen.

Klingt wie ein Traum und ist es auch. – Sofern man ausreichend Zeit hat, sich durch den Informationsdschungel zu kämpfen…

Flare

Hier kommt jetzt Madcap Flare ins Spiel. Das Programm ist sozusagen die gegenüberliegende Andockstelle für Informationen: Während Confluence mit jedem aktuellen Browser auf allen Geräten mit Inhalten gefüttert werden kann (auf Mobilgeräten auch per App), braucht MadCap Flare ganz traditionell eine Installation auf einem PC, eine Lizenz und eine festgelegte Ordnerstruktur, in der die Informationen abgelegt werden, damit die Verknüpfungen funktionieren. Während Confluence ein Spielplatz ist, ist Flare ein Parkplatz. Hier geht nichts ohne Ordnung.

Diese Ordnung ist allerdings wichtig für die Vermittlung technischer Inhalte, denn die User benötigen kein Brainstorming, die wollen Antworten auf ihre Fragen – und das möglichst rasch. Diese Anforderung zu erfüllen, ist Aufgabe der technischen Redaktion. Das Werkzeug dafür ist Flare.

Glücklicherweise leben diese beiden Seiten der gleichen Medaille nicht in getrennten Welten. Auf beiden Seiten sitzen Menschen, die Informationen vermitteln wollen und die gleiche Technologie: HTML. Man muss also nicht Texte kopieren, umstricken, aufhübschen und zur Korrektur wieder zurückschicken an die Produktverantwortlichen, dann die Inhalte anpassen und zur Freigabe wieder losschicken. Und das am besten in einem Austauschformat, auf das sich beide Seiten vorher geeinigt haben.

MadCap Flare besitzt nämlich eine Schnittstelle zu Confluence. Und das optimiert den Redaktionsprozess erheblich.

Let the Nerds begin.

Dokumentationsprozess, optimiert

Die Idee hinter dem Prozess ist, die Vorzüge der beiden Programme zum richtigen Zeitpunkt zu nutzen.

• Recherche: die Redaktion erfasst zusammen mit den Produktverantwortlichen die für eine technische Dokumentation erforderlichen Informationen (Abläufe, Tätigkeiten, Zertifikate, Bilder, Filme, …) und legt diese Inhalte in Confluence in einem eigenen „Space“ an. Auf diesen Space haben alle Beteiligte Zugriff.
• Auswertung: die Redaktion gliedert in Confluence die Inhalte in einem ersten Schritt nach ihrem Instruktionsgehalt, z.B. Produktbeschreibung, Installation, Wartung, Bedienung, … Die Produktverantwortlichen können den Space „beobachten“ und werden über Änderungen informiert. Sie können jederzeit selbst ergänzen, korrigieren oder kommentieren. Dadurch findet der gesamte Recherche- und Korrekturprozess in einer endlosen Schleife statt, deren einzelne Tätigkeiten idealerweise in JIRA abgebildet werden.²
• Finalisierung: Zu einem bestimmten Zeitpunkt (den die Produktverantwortlichen – wie es sich für ein Projekt gehört – festlegen) werden die Inhalte in Flare importiert, indem man Project > Import > Confluence pages wählt und den gewünschten Space auswählt.

• Publikation: Das oder die importierten Topics werden in Flare von der Redaktion an die korrekte Stelle in der Anleitung verschoben, wobei die Links erhalten bleiben. Die Bilder werden gegebenenfalls ausgetauscht, wenn beispielsweise Vektorgrafiken (SVG) statt Rasterbildern (PNG, JPG) verwendet werden sollen (für Print). Die für eine Anleitung zusätzlichen Inhalte (Impressum, Sicherheitsinformationen, …) liegen bereits in Flare vor. Abschließend wird das Handbuch als Komplettfassung (PDF) ausgegeben und den Produktverantwortlichen zur endgültigen Freigabe vorgelegt.³
• Distribution: Ist die Freigabe erfolgt, wird mit Flare publiziert – sei es als Onlinehilfe oder als PDF mit Querverweisen, Inhaltsverzeichnis und – falls es unbedingt notwendig sein sollte – auch mit Index.

Fazit

Dieser Prozess erspart beiden Seiten das umständliche Verschieben von PDF-Dokumenten, oder die unproduktive Kommentierung per Mail („Auf Seite 123 muss Hammer fett geschrieben sein“). Da sich Confluence sehr leicht bedienen lässt, benötigen die Produktverantwortlichen keine zusätzlichen Schulungen oder Unterstützung im Korrekturlauf – was auch die Chefs glücklich macht…

1. Die Firma stellt auch JIRA her, das ich in einem anderen Beitrag vorgestellt hatte. Es bedient sich allerdings genauso einfach. ↩︎
2. Durch die Erfassung der erforderlichen Tätigkeiten („To-Dos“) haben alle Beteiligten jederzeit den kompletten Überblick über den Status Quo. ↩︎
3. Dafür ist die Adobe Cloud hervorragend geeignet, mit der sich am PDF-Dokument zusammenarbeiten lässt, um finale Änderungen „in Echtzeit“ zu bearbeiten. Idealerweise sollte der Inhalt aber bereits korrekt sein… ↩︎