Topic-basiertes Schreiben mit MadCap Flare

Äh, Topics? Im Bei­trag Topics: Infor­ma­ti­ons­häpp­chen hirn­ge­recht ser­vie­ren wur­de bereits beschrie­ben, dass Topics klei­ne Ein­hei­ten in der Tech­ni­schen Doku­men­ta­ti­on sind, mit denen dem Leser (und auch dem Redak­teur) die Erfas­sung situa­tiv rele­van­ter Infor­ma­tio­nen erleich­tert wer­den soll. Wie aber macht man das? Ganz ein­fach: Man stellt den zu beschrei­ben­den Sach­ver­halt auf den Kopf und schüt­telt so lan­ge, bis nichts mehr her­aus­fällt. Dann dreht man es wie­der um und beginnt mit der Erfas­sung. Alles klar?

Wie bei den Häpp­chen spielt es auch für Topics zunächst kei­ne Rol­le, wo sie spä­ter ser­viert wer­den. Ob es bei der Aus­ga­be um ein gedruck­tes Doku­ment, eine Online­hil­fe oder eine PDF, einen kon­text­sen­si­ti­ven Hil­fe­text auf dem Bild­schirm oder ein e‑Lear­ning-Doku­ment geht, hat mit der Infor­ma­ti­on selbst nichts zu tun. Ent­spre­chend muss sie so kon­zi­piert wer­den, dass sie ohne Nach­ar­beit über­all ein­ge­setzt wer­den kann.

Posi­ti­on ist Bedeu­tung

Durch die Posi­ti­on der Topics bestimmt sich meist auch ihre Bedeu­tung. Aller­dings muss der Sach­ver­halt dann auch neu­tral beschrie­ben wer­den: die Infor­ma­ti­on muss so abge­fasst sein, dass jeg­li­cher Bezug auf eine bestimm­te Posi­ti­on ver­mie­den wird.

Meist wird dies in Online­hil­fe-Sys­te­men bereits umge­setzt – sofern sie modu­lar ange­legt sind. In der klas­si­schen Tech­ni­schen Doku­men­ta­ti­on im Maschi­nen­bau ist das noch nicht so weit ent­wi­ckelt, da die meis­ten Pro­zes­se aus phy­si­ka­li­schen Gege­ben­hei­ten line­ar sind und der Redak­teur dadurch ver­lei­tet ist, ent­spre­chend uni­di­rek­tio­nal zu den­ken. Die Schwie­rig­keit ist daher, uni­ver­sell ein­setz­ba­re Topics zu iden­ti­fi­zie­ren und zu bestim­men, was sie beinhal­ten wer­den – und die Bedeu­tungs­zu­wei­sung dem Kon­text zu über­las­sen. Man braucht also eine Struk­tur. Wie man das machen kann, steht auch im Bei­trag Anla­gen­do­ku­men­ta­tio­nen pla­nen und steu­ern: Erst den­ken, dann schrei­ben).

Struk­tur und Pro­zess

Zwei Schrit­te wei­ter. Wir stel­len uns vor, die­se Struk­tur ist vor­han­den, alle Topics sind bestimmt. Für die Umset­zung neh­men wir das Pro­gramm Mad­Cap Fla­re, selbst wenn wir nicht für eine Online-Aus­ga­be schrei­ben. (Natür­lich eig­net sich dazu jedes Pro­gramm, mit dem Inhal­te modu­lar erfasst und zusam­men­ge­setzt wer­den kön­nen.)

Kon­zept

Wer schon ein­mal mit Robo­help oder ähn­li­chen Edi­to­ren zum Erzeu­gen einer Online­hil­fe gear­bei­tet hat, kommt mit der Benut­zung des Pro­gramms zwar schnel­ler zurecht, muss aber dar­auf ach­ten, das Pro­gramm nicht in die Schub­la­de „Soft­ware­do­ku­men­ta­ti­on“ zu wer­fen. Denn Fla­re kann als Grund­la­ge für zahl­rei­che Publi­ka­ti­ons­me­di­en die­nen – ein­schließ­lich Druck.

Dazu bie­tet Fla­re Funk­tio­nen, wie sie vor allem in der tech­ni­schen Doku­men­ta­ti­on wich­tig sind. Dort zählt die Kon­sis­tenz in Lay­out, Stil und Auf­bau zu den wich­tigs­ten Zie­len. Daher wer­den in Fla­re (wie in ande­ren HTML-Edi­to­ren auch) alle Topics nach der Erstel­lung in ein Tem­p­la­te gela­den, das das spä­te­re Aus­se­hen („Look & Feel“) der Aus­ga­be defi­niert. Das bedeu­tet umge­kehrt auch, dass alle Topics unab­hän­gig von ihrem spä­te­ren Aus­se­hen erfasst wer­den müs­sen. Sie wer­den als ein­fa­che HTML-Datei­en abge­legt und erst bei der Aus­ga­be abhän­gig vom Aus­ga­be­me­di­um mit For­mat­vor­la­gen, Navi­ga­ti­ons­ele­men­ten, Such­funk­tio­nen, Index, Sei­ten­zah­len usw. ver­se­hen. Das Lay­out beim Erfas­sen der Inhal­te dient daher nur der opti­schen Kon­trol­le, ist aber nicht iden­tisch zur spä­te­ren Aus­ga­be. Die­se spielt näm­lich für die Erfas­sung der Inhal­te kei­ne Rol­le.

Erst impor­tie­ren oder doch lie­ber erst auf­räu­men?

Fla­re ist bei der Daten­über­nah­me äußerst tole­rant: Bereits bestehen­de Inhal­te aus den unter­schied­lichs­ten Quel­len las­sen sich impor­tie­ren und dann inner­halb des Fla­re-Ver­zeich­nis­baums able­gen. An die­ser Stel­le grei­fen aller­dings die Beson­der­hei­ten der Aus­zeich­nungs­spra­chen wie HTML: alle Infor­ma­tio­nen, also auch Gra­fi­ken und Bil­der müs­sen inner­halb eines Stamm­ver­zeich­nis­ses lie­gen, da eine Aus­zeich­nungs­spra­che nur aus Text besteht und ande­re Datei­en wie Fil­me oder eben Bil­der refe­ren­ziert. Was nicht erreicht wer­den kann, weil es auf einem ande­ren Lauf­werk liegt, das gera­de nicht zur Ver­fü­gung steht, wird auch nicht ange­zeigt.

Aller­dings ist der direk­te Import nicht unbe­dingt der idea­le Weg, denn die impor­tier­ten Doku­men­te könn­ten mit­un­ter nicht the­men­zen­triert erstellt wor­den sein, son­dern eben „klas­sisch“. Da ste­hen dann Funk­ti­ons­be­schrei­bun­gen neben Warn­hin­wei­sen oder Bedie­nung und War­tung wird mun­ter gemischt. Daher ist es mög­li­cher­wei­se effi­zi­en­ter, vor dem Import noch­mals Hand an den Inhalt anzu­le­gen und die Daten­quel­len auf­zu­räu­men oder so zu „zer­schnei­den“, dass wir die Inhal­te nur bruch­stück­wei­se über­neh­men, bei­spiels­wei­se, indem wir vor dem Import vie­le klei­ne Topics mit einem Edi­tor anle­gen.

Daher brau­chen wir zunächst eine Lis­te der Topics, die wir uns anle­gen, um die Inhal­te spä­ter dort zu erfas­sen. Die­se Lis­te erfor­dert eine gewis­se Pla­nung (dazu auch Anti­zi­pa­ti­ves Schrei­ben: Wei­ter als der eige­ne Hori­zont).

Anle­gen

Gehen wir jetzt davon aus, dass die­se Glie­de­rung exis­tiert und wir also eine Vor­stel­lung davon haben, wel­che Topics benö­tigt wer­den, und wie wir sie glie­dern kön­nen.

Auf geht’s:

1. Fla­re star­ten und ein neu­es Pro­jekt anle­gen. Am bes­ten gleich ein lee­res Pro­jekt anle­gen, denn wir haben ja schon eine Struk­tur.
2. Pro­jekt­vor­la­ge aus­wäh­len. Die­se lässt sich spä­ter anpas­sen und erwei­tern, legt aber schon mal die benö­tig­ten Ver­zeich­nis­se und das pri­mä­re Aus­ga­be­for­mat an. Das darf auch PDF sein, für das Mad­Cap meh­re­re Vor­la­gen anbie­tet.
   Die Mög­lich­keit, ein Sys­tem aus HTML-Doku­men­ten wie eine Inter­net­sei­te aus­zu­bau­en und dann als gedruck­te Doku­men­ta­ti­on zu lie­fern, ist eine der Beson­der­hei­ten. Der Vor­teil davon ist, dass es zwar recht ein­fach ist, von einer Inter­net­sei­te ein umfang­rei­ches PDF-Doku­ment zu pro­du­zie­ren, umge­kehrt aber sehr müh­sam.

Fla­re hat uns mit der Aus­wahl der Vor­la­ge die ers­te Arbeit schon abge­nom­men und Ord­ner ange­legt, in die sinn­vol­ler­wei­se die Topics bezie­hungs­wei­se Bil­der gelegt wer­den. Da die­se Ord­ner von Fla­re ver­wal­tet wer­den, muss man sich jetzt nur ange­wöh­nen, das gesam­te Kon­strukt als eine ein­zi­ge Datei zu betrach­ten. Das Umbe­nen­nen oder Ver­schie­ben von Ord­nern und Datei­en soll­ten wir daher immer in Fla­re durch­füh­ren – und nicht im Datei­sys­tem.

Nun kommt die Arbeit, für die wir Redak­teu­re bezahlt wer­den: Inhal­te erfas­sen und zu Topics bün­deln.

Erfas­sen

Das Erfas­sen von Inhal­ten in der Tech­ni­schen Doku­men­ta­ti­on ist rei­nes Hand­werk. Also erstel­len wir in Fla­re zunächst ana­log zu unse­ren Topics eige­ne Sei­ten in den jewei­li­gen Ver­zeich­nis­sen in Fla­re.

Sobald alle Topics ange­legt sind (zunächst unab­hän­gig von ihrer geplan­ten Hier­ar­chie), begin­nen wir mit dem Fül­len. Es spielt über­haupt kei­ne Rol­le, mit wel­chem Topic wir begin­nen, denn alle haben ja spä­ter ihren Platz und damit auch ihre Bedeu­tung.

Bei der Erfas­sung der Inhal­te kön­nen wir dann eigent­lich so vor­ge­hen, wie aus einem Text­edi­tor bekannt: Lis­ten, Tabel­len, Gra­fi­ken und was sonst für eine ver­ständ­li­che Über­mitt­lung der Infor­ma­tio­nen not­wen­dig sein kann. Den­noch steht hin­ter jedem Inhalts­bau­stein die For­de­rung, so genau wie nötig, aber so all­ge­mein­gül­tig wie mög­lich zu schrei­ben.

Wie es sich für einen guten Edi­tor gehört, kön­nen die Gra­fi­ken, Bil­der und Fil­me natür­lich direkt mit einem exter­nen Pro­gramm bear­bei­tet wer­den. Gera­de wer mit dem Pro­gramm Frame­Ma­ker ver­traut ist, fin­det sich hier sehr schnell zurecht: Quer­ver­wei­se wer­den genau­so ange­legt, es gibt Bedin­gungs­for­ma­te und Varia­blen, die für die Publi­ka­ti­on zum Tra­gen kom­men kön­nen. Sogar Text­ein­schü­be, also mehr­fach ver­wend­ba­re Text­bau­stei­ne, sind mög­lich: in Fla­re hei­ßen sie „Snip­pets“ und wer­den wie auch Bil­der im Ord­ner „Resour­cen“ abge­legt und dort ange­passt. Sobald sie geän­dert wer­den, wer­den die­se Ände­run­gen in allen Topics nach­ge­zo­gen.

Selbst der aus der Arbeit mit struk­tu­rier­ten Doku­men­ten in Frame­Ma­ker bekann­te „Struk­tur­baum“ fehlt nicht: Die Ele­men­te wer­den in Form klei­ner Recht­ecke am lin­ken Bild­rand dar­ge­stellt. Auch mit ihnen lässt sich arbei­ten, sobald man sich mit den Grund­zü­gen der Aus­zeich­nungs­spra­chen ver­traut gemacht hat.

Die „Dos“ und die „Don’ts“

Aber jetzt mal ganz kon­kret: Wor­auf soll­te man ach­ten beim Schrei­ben? Nach­fol­gend eine klei­ne Hil­fe zu den „Dos“ und den „Dont’s“, also so, wie man es ger­ne beim Schrei­ben pas­siert und so, wie es sich opti­mie­ren lässt.

• Kon­kre­te Bezü­ge zum Gegen­stand soweit wie mög­lich ver­mei­den, so all­ge­mein wie nur mög­lich schrei­ben.
• Topics nicht inein­an­der ver­schach­teln (Trans­klu­si­on), son­dern auf­ein­an­der ver­wei­sen (Hyper­lin­king). Ver­wei­se sind ein­fa­cher zu ver­wal­ten als Text­bau­stei­ne.

Dazu schüt­teln wir zunächst alles her­aus. Und dann ergän­zen wir nach reif­li­cher Über­le­gung nur das Not­wen­digs­te.

Bei­spiel: In einem Topic zum The­ma „Bau­teil in einem Gehäu­se aus­tau­schen“ (oder ein­set­zen bzw. her­aus­neh­men) taucht der fol­gen­de Satz auf: Neh­men Sie den Deckel und den Dicht­ring mit Hil­fe eines Schrau­ben­dre­hers an den vier Befes­ti­gungs­schrau­ben ab. Die­ser Satz besitzt – unab­hän­gig davon, ob die per­so­na­li­sier­te Form gewählt wer­den soll oder muss – die Kern­aus­sa­ge Neh­men Sie den Deckel ab (oder eben noch kür­zer Deckel abneh­men). Han­delt es sich um eine Tätig­keit, die eine Fach­kraft durch­füh­ren soll, wür­de dies genü­gen. War­um?

• Dass der Mensch bei einem ver­schraub­ten Deckel zum Werk­zeug grei­fen wird, ist ja anzu­neh­men. Ele­gan­ter­wei­se könn­te man dem gesam­ten Hand­lungs­pa­ket noch das benö­tig­te Werk­zeug vor­an­stel­len (Hilfs­mit­tel: Schrau­ben­dre­her). Aber auch das nur, wenn es kei­nen Deckel gibt, der mit einem Schrau­ben­schlüs­sel geöff­net wer­den muss, denn sonst ist die Beschrei­bung nicht mehr all­ge­mein­gül­tig.
• Dass es sich um Befes­ti­gungs­schrau­ben han­delt ist klar, das muss man nicht eigens dazu schrei­ben.
• Falls der Dicht­ring am Deckel befes­tigt ist, wird er sowie­so mit dem Deckel abge­nom­men, dann muss das auch nicht erwähnt wer­den. (Falls der Dicht­ring aus­ge­tauscht wer­den soll, machen wir dar­aus ein eige­nes Topic.)
• Dar­über hin­aus ist die Anga­be zur Anzahl der Schrau­ben über­flüs­sig, denn wenn nicht alle Schrau­ben gelöst wur­den, kann der Deckel ja nicht abge­nom­men wer­den.
• Soll­te es jedoch meh­re­re Deckel geben, die viel­leicht auch im Zusam­men­hang mit die­sem Hand­lungs­pa­ket abge­nom­men wer­den müs­sen, benö­ti­gen wir eine gra­fi­sche Dar­stel­lung, mit einer Num­me­rie­rung, die wir natür­lich im Hand­lungs­schritt ergän­zen müs­sen: Deckel (1) abneh­men.

Der Satz ist jetzt kür­zer und auch wesent­lich bil­li­ger in der Über­set­zung, denn dort kön­nen Zah­len auto­ma­tisch über­setzt wer­den. Kommt die­ser Satz in meh­re­ren Topics vor mit unter­schied­li­chen Zah­len, erkennt das Über­set­zungs­pro­gramm, dass es sich um einen iden­ti­schen Satz han­delt und tauscht die Zah­len auto­ma­tisch aus. Das spart viel Zeit und Geld.

Die­se gedank­li­chen Pro­zes­se, die uns jetzt so schön den Satz haben kür­zen las­sen, müs­sen wir aller­dings auf jeden Satz anwen­den. Eine Sysi­pho­sauf­ga­be, vor allem wenn ein bereits bestehen­der Doku­men­ten­be­stand nach­ge­ar­bei­tet wer­den müss­te. Hier ist der Kon­junk­tiv beab­sich­tigt, denn natür­lich lässt sich dies nicht für jeden Satz in einem Rutsch erle­di­gen. Aller­dings unter­stützt uns an die­ser Stel­le die Arbeit mit Topics: Ein­mal bear­bei­tet, kann die­ses Topic ja als abge­schlos­sen betrach­tet wer­den und es wird nur noch dar­auf ver­wie­sen. Die Arbeit macht man also nur ein­mal.

Fazit

Der ein­zig wesent­li­che Unter­schied zu einem Pro­gramm wie Frame­Ma­ker sind somit die Topics, die durch ihre Fle­xi­bi­li­tät und neu­tra­les For­mat spä­ter für eine Viel­zahl unter­schied­li­cher Aus­ga­be­for­ma­te geeig­net sind: ePub genau­so wie Word, Frame­Ma­ker oder Online­hil­fe. Dem so genann­ten „Sin­g­le­sour­ce-Publi­shing“ kommt man mit Mad­Cap Fla­re sehr nahe – sofern die Inhal­te Topic-basiert erfasst wur­den.