MadCap Flare und Atlassian Confluence: das Powercouple

Fest­hal­ten, es wird nerdig. Denn es geht um Pro­zes­se in der Tech­ni­k­re­dak­ti­on – nicht, dass man auch als Außen­sei­ter immer dazu­ler­nen kann, aber man soll­te schon etwas Erfah­rung mit der effi­zi­en­ten Pro­duk­ti­on didak­ti­scher Inhal­te besit­zen.

You have been war­ned.

Ich habe mich an ande­rer Stel­le schon über die Vor­zü­ge des topic-basier­ten Erfas­sens tech­ni­scher Inhal­te aus­ge­brei­tet (Topics: Infor­ma­ti­ons­häpp­chen hirn­ge­recht ser­vie­ren), das möch­te ich hier über­sprin­gen. Ein recht gut geeig­ne­tes Tool für die­sen Zweck ist Mad­Cap Fla­re, das eine topic-basier­te Arbeits­wei­se erlaubt, ohne eine Daten­bank zugrun­de zu legen, wie es bei­spiels­wei­se Redak­ti­ons­sys­te­me machen, die – zu Recht – ein Viel­fa­ches kos­ten.

Con­fluence

Das ande­re Tool, um das es hier gehen soll, ist eigent­lich ein Wiki: Con­fluence von der Fir­ma Atlas­si­an.¹ Ein Wiki ist nor­ma­ler­wei­se nicht unbe­dingt dazu geeig­net, Infor­ma­tio­nen so zu struk­tu­rie­ren, wie man sie für Topics benö­tigt, da man die Infor­ma­tio­nen ein­fach hin­ein­schüt­ten und dann mit­ein­an­der ver­knüp­fen kann, ohne sich an bestimm­te Regeln zum Auf­bau oder der Auf­find­bar­keit zu hal­ten: Man legt ein­fach eine neue Sei­te an und klopft den Inhalt hin­ein, nagelt ein paar Fotos dazu und fer­tig ist die Kis­te.

Da Con­fluence über exqui­si­te Fil­ter- und Such­funk­tio­nen ver­fügt, ist das Wie­der­auf­fin­den der Sei­ten und Inhal­te kein Pro­blem. Dar­über hin­aus bie­tet die App auch eine Kom­men­tar­funk­ti­on, eine Kol­la­bo­ra­ti­ons­funk­ti­on und eine Anmer­kungs­funk­ti­on an – also alles, was man zur Erfas­sung und Über­ar­bei­tung der Inhal­te benö­tigt. Wer sich aus­schließ­lich online bewegt und Zugriff auf die Sei­ten hat, kann natür­lich auch mit Mobil­ge­rä­ten dar­auf zugrei­fen und die Inhal­te aktua­li­sie­ren. Die Ände­run­gen wer­den auto­ma­tisch pro­to­kol­liert. Dadurch kann man alte Inhal­te ver­glei­chen und gege­be­nen­falls wie­der­her­stel­len.

Klingt wie ein Traum und ist es auch. – Sofern man aus­rei­chend Zeit hat, sich durch den Infor­ma­ti­ons­dschun­gel zu kämp­fen…

Fla­re

Hier kommt jetzt Mad­cap Fla­re ins Spiel. Das Pro­gramm ist sozu­sa­gen die gegen­über­lie­gen­de Andock­stel­le für Infor­ma­tio­nen: Wäh­rend Con­fluence mit jedem aktu­el­len Brow­ser auf allen Gerä­ten mit Inhal­ten gefüt­tert wer­den kann (auf Mobil­ge­rä­ten auch per App), braucht Mad­Cap Fla­re ganz tra­di­tio­nell eine Instal­la­ti­on auf einem PC, eine Lizenz und eine fest­ge­leg­te Ord­ner­struk­tur, in der die Infor­ma­tio­nen abge­legt wer­den, damit die Ver­knüp­fun­gen funk­tio­nie­ren. Wäh­rend Con­fluence ein Spiel­platz ist, ist Fla­re ein Park­platz. Hier geht nichts ohne Ord­nung.

Die­se Ord­nung ist aller­dings wich­tig für die Ver­mitt­lung tech­ni­scher Inhal­te, denn die User benö­ti­gen kein Brain­stor­ming, die wol­len Ant­wor­ten auf ihre Fra­gen – und das mög­lichst rasch. Die­se Anfor­de­rung zu erfül­len, ist Auf­ga­be der tech­ni­schen Redak­ti­on. Das Werk­zeug dafür ist Fla­re.

Glück­li­cher­wei­se leben die­se bei­den Sei­ten der glei­chen Medail­le nicht in getrenn­ten Wel­ten. Auf bei­den Sei­ten sit­zen Men­schen, die Infor­ma­tio­nen ver­mit­teln wol­len und die glei­che Tech­no­lo­gie: HTML. Man muss also nicht Tex­te kopie­ren, umstri­cken, auf­hüb­schen und zur Kor­rek­tur wie­der zurück­schi­cken an die Pro­dukt­ver­ant­wort­li­chen, dann die Inhal­te anpas­sen und zur Frei­ga­be wie­der los­schi­cken. Und das am bes­ten in einem Aus­tausch­for­mat, auf das sich bei­de Sei­ten vor­her geei­nigt haben.

Mad­Cap Fla­re besitzt näm­lich eine Schnitt­stel­le zu Con­fluence. Und das opti­miert den Redak­ti­ons­pro­zess erheb­lich.

Let the Nerds begin.

Doku­men­ta­ti­ons­pro­zess, opti­miert

Die Idee hin­ter dem Pro­zess ist, die Vor­zü­ge der bei­den Pro­gram­me zum rich­ti­gen Zeit­punkt zu nut­zen.

• Recher­che: die Redak­ti­on erfasst zusam­men mit den Pro­dukt­ver­ant­wort­li­chen die für eine tech­ni­sche Doku­men­ta­ti­on erfor­der­li­chen Infor­ma­tio­nen (Abläu­fe, Tätig­kei­ten, Zer­ti­fi­ka­te, Bil­der, Fil­me, …) und legt die­se Inhal­te in Con­fluence in einem eige­nen „Space“ an. Auf die­sen Space haben alle Betei­lig­te Zugriff.
• Aus­wer­tung: die Redak­ti­on glie­dert in Con­fluence die Inhal­te in einem ers­ten Schritt nach ihrem Instruk­ti­ons­ge­halt, z.B. Pro­dukt­be­schrei­bung, Instal­la­ti­on, War­tung, Bedie­nung, … Die Pro­dukt­ver­ant­wort­li­chen kön­nen den Space „beob­ach­ten“ und wer­den über Ände­run­gen infor­miert. Sie kön­nen jeder­zeit selbst ergän­zen, kor­ri­gie­ren oder kom­men­tie­ren. Dadurch fin­det der gesam­te Recher­che- und Kor­rek­tur­pro­zess in einer end­lo­sen Schlei­fe statt, deren ein­zel­ne Tätig­kei­ten idea­ler­wei­se in JIRA abge­bil­det wer­den.²
• Fina­li­sie­rung: Zu einem bestimm­ten Zeit­punkt (den die Pro­dukt­ver­ant­wort­li­chen – wie es sich für ein Pro­jekt gehört – fest­le­gen) wer­den die Inhal­te in Fla­re impor­tiert, indem man Pro­ject > Import > Con­fluence pages wählt und den gewünsch­ten Space aus­wählt.

• Publi­ka­ti­on: Das oder die impor­tier­ten Topics wer­den in Fla­re von der Redak­ti­on an die kor­rek­te Stel­le in der Anlei­tung ver­scho­ben, wobei die Links erhal­ten blei­ben. Die Bil­der wer­den gege­be­nen­falls aus­ge­tauscht, wenn bei­spiels­wei­se Vek­tor­gra­fi­ken (SVG) statt Ras­ter­bil­dern (PNG, JPG) ver­wen­det wer­den sol­len (für Print). Die für eine Anlei­tung zusätz­li­chen Inhal­te (Impres­sum, Sicher­heits­in­for­ma­tio­nen, …) lie­gen bereits in Fla­re vor. Abschlie­ßend wird das Hand­buch als Kom­plett­fas­sung (PDF) aus­ge­ge­ben und den Pro­dukt­ver­ant­wort­li­chen zur end­gül­ti­gen Frei­ga­be vor­ge­legt.³
• Dis­tri­bu­ti­on: Ist die Frei­ga­be erfolgt, wird mit Fla­re publi­ziert – sei es als Online­hil­fe oder als PDF mit Quer­ver­wei­sen, Inhalts­ver­zeich­nis und – falls es unbe­dingt not­wen­dig sein soll­te – auch mit Index.

Fazit

Die­ser Pro­zess erspart bei­den Sei­ten das umständ­li­che Ver­schie­ben von PDF-Doku­men­ten, oder die unpro­duk­ti­ve Kom­men­tie­rung per Mail („Auf Sei­te 123 muss Ham­mer fett geschrie­ben sein“). Da sich Con­fluence sehr leicht bedie­nen lässt, benö­ti­gen die Pro­dukt­ver­ant­wort­li­chen kei­ne zusätz­li­chen Schu­lun­gen oder Unter­stüt­zung im Kor­rek­tur­lauf – was auch die Chefs glück­lich macht…

1. Die Fir­ma stellt auch JIRA her, das ich in einem ande­ren Bei­trag vor­ge­stellt hat­te. Es bedient sich aller­dings genau­so ein­fach. ↩︎
2. Durch die Erfas­sung der erfor­der­li­chen Tätig­kei­ten („To-Dos“) haben alle Betei­lig­ten jeder­zeit den kom­plet­ten Über­blick über den Sta­tus Quo. ↩︎
3. Dafür ist die Ado­be Cloud her­vor­ra­gend geeig­net, mit der sich am PDF-Doku­ment zusam­men­ar­bei­ten lässt, um fina­le Ände­run­gen „in Echt­zeit“ zu bear­bei­ten. Idea­ler­wei­se soll­te der Inhalt aber bereits kor­rekt sein… ↩︎