MadCap Analyzer: Gabelstapler für Onlinehilfen

Bevor Sie wei­ter­le­sen: Ana­ly­zer ist eine Ergän­zung zu Mad­Cap Fla­re. Ohne Letz­te­res nutzt Ihnen der Ana­ly­zer wenig. Mit Fla­re aller­dings ist das der Gabel­stap­ler für die schwe­ren Sachen.

Über die Vor­zü­ge von Fla­re für das „Sin­gle-source-mul­tich­an­nel-publi­shing“ muss ich an die­ser Stel­le kein Wort ver­lie­ren – das habe ich an ande­rer Stel­le schon mehr­mals (sie­he Online­do­ku­men­ta­ti­on mit Fla­re 12: Any color you like und Topic-basier­tes Schrei­ben mit Mad­Cap Fla­re). Vor­aus­set­zung ist daher, dass Sie bereits begon­nen oder wie ich – qua­si mit ver­schärf­ten Bedin­gun­gen – ein kom­plet­tes Robo­help-Sys­tem über­nom­men haben. Wie auch immer: die­se Infor­ma­tio­nen stam­men aus unter­schied­li­chen Quel­len von unter­schied­li­chen Autoren zu unter­schied­li­chen Zeit­punk­ten. Sin­gle-source Publi­shing bedeu­tet ja mit­nich­ten, dass die Infor­ma­tio­nen, die aus einer Quel­le kom­men, auch von einer Quel­le stam­men. Im Gegen­teil, es sam­melt sich trotz „guten Wil­lens und ste­ten Bemü­hens“ im Lau­fe der Jah­re doch eine Men­ge an „Grem­lins“ an:

• Ver­wais­te Links, die auf nicht mehr vor­han­de­ne Tex­te oder Bil­der ver­wei­sen
• Son­der­zei­chen im Text (vom Kopie­ren und Anpas­sen aus ande­ren Pro­gram­men wie Word, die sach­frem­de Abtei­lun­gen wie Ver­trieb oder Mar­ke­ting lie­fern), die nicht Uni­code-kon­form sind oder völ­lig anders belegt (z.B. eng­li­sche Anfüh­rungs­zei­chen in deut­schen tex­ten)
• Tex­te und Sät­ze, die sehr ähn­lich klin­gen und eigent­lich ver­ein­heit­licht wer­den müss­ten („Lösen Sie die Schrau­ben und neh­men Sie den Deckel ab.“ oder „Lösen Sie die Schrau­ben und öff­nen Sie den Deckel.“)
• Text­for­ma­te, die nicht iden­tisch zuge­wie­sen wur­den
• Wie­der­keh­ren­de For­mu­lie­run­gen, die man eigent­lich als „Frag­ment“ (ST4) oder „Text­ein­schub“ (Frame­Ma­ker) oder „Snip­pet“ (InDe­sign bzw. Fla­re) füh­ren könn­te, damit sie nur an einer Stel­le geän­dert wer­den müs­sen und in 25 Text­pas­sa­gen aktua­li­siert wer­den

Gera­de wie­der­keh­ren­de For­mu­lie­run­gen sind in der Soft­ware-Doku­men­ta­ti­on beson­ders häu­fig, denn modu­la­re Tex­te ver­lan­gen nach einer kon­sis­ten­ten Benut­zer­füh­rung: Tätig­kei­ten wie „Über­neh­men“ und „Spei­chern“ wer­den häu­fig vom Benut­zer ver­langt und tau­chen daher auch ent­spre­chend häu­fig in der Doku­men­ta­ti­on auf (sonst ist die Hand­lung nicht abge­schlos­sen). Die­se nun jedes­mal neu zu schrei­ben öff­net den Abwei­chun­gen Tür und Tor – vor allem, wenn die beschrei­be­nen Tätig­kei­ten erst im Lauf von Jah­ren dazu kom­men („Wie hat­te ich das letz­tes Jahr beschrie­ben?“).

Wenn man das von vorn­her­ein weiß, las­sen sich die ent­spre­chen­den Snip­pets in Fla­re pri­ma anle­gen und ein­set­zen.¹

Was aber, wenn die Soft­ware „lebt“ und neue Funk­tio­nen dazu kom­men und alte ange­passt wer­den? Aus meh­re­ren hun­dert Topics die zu fin­den, die eines Snip­pets wür­dig sind, ist eine sehr zeit­auf­wän­di­ge Arbeit.

Hier hilft der Ana­ly­zer

Um den Ana­ly­zer zum Arbei­ten zu bewe­gen, star­tet man das Pro­gramm ent­we­der direkt und öff­net dann das Fla­re-Pro­jekt, oder – ein­fa­cher – man star­tet den Ana­ly­zer direkt aus dem geöff­ne­ten Pro­jekt her­aus.

Der Vor­teil einer „Stand-alo­ne-Lösung“ liegt auf der Hand: Die Tex­te kön­nen von einem Autor kon­trol­liert wer­den („Vier-Augen-Prin­zip“), der einen tech­ni­schen Blick auf die Doku­men­te hat. Der Ana­ly­zer unter­sucht näm­lich die gesam­ten Doku­men­te auf ver­wais­te Links, defek­te Links, benutz­te und nicht benutz­te Sti­le (CSS-For­ma­te), und auch auf mög­li­che Struk­tur­pro­ble­me wie meh­re­re Über­schrif­ten in einem Topic².

Nach der Ana­ly­se des Pro­jekts zeigt der Ana­ly­zer eine Über­sicht zu allen Fra­gen, die ihm auf­ge­fal­len sind. An die­ser Stel­le soll es aber nur um die Snip­pets gehen.

Snip­pets erstel­len und ein­set­zen

Wir öff­nen jetzt in der Lis­te die Vor­schlä­ge, die Ana­ly­zer zu mög­li­chen Wie­der­ver­wen­dun­gen macht. Nur zwei? OK. Das sieht ja nun nicht schlimm aus.³ Ein Dop­pel­klick auf einen Ein­trag öff­net das Topic und hebt die frag­li­che Stel­le her­vor.

Mit der rech­ten Maus­tas­te auf die Absatz­mar­kie­rung kli­cken und „Crea­te Snip­pet…“ wäh­len.

Ana­ly­zer ver­langt nach einem Namen für das Snip­pet und zeigt es ohne For­ma­tie­rung an. Wenn man „Replace Source Con­tent with the New Snip­pet“ akti­viert, wird das gewähl­te Text­stück aus­ge­tauscht: für den Leser sieht das gleich aus, in Fla­re wird die­ser Absatz aber in einem Ord­ner „Snip­pets“ abge­legt und hier neu ver­linkt.

Der nächs­te Text hat aber noch kein Snip­pet. Daher kopie­ren wir das ein­ge­füg­te Snip­pet und öff­nen das fol­gen­de Topic. Und jetzt wird ein­fach mar­kiert und ein­ge­fügt. Fer­tig.

Nach dem Spei­chern wird der Absatz aus einer ein­zi­gen Quel­le bestückt. Sobald sich (in die­sem Bei­spiel) die IP-Adres­se ändert, wird sie auto­ma­tisch über­all ange­passt. So wie es sich gehört für eine gute Doku­men­ta­ti­on.

Wie­der ein­mal „Suchen & Erset­zen“ gespart. Das ist näm­lich sowas von letz­tes Jahr­tau­send.

Bild­quel­le: 179​len​gyea​.blog​spot​.com

---

1. Bei­spiels­wei­se für Sicher­heits­hin­wei­se. ↩

2. Das ist in einem HTML mög­lich, wider­spricht aber der modu­la­ren Logik, nach der ein Topic eben nur eine Über­schrift haben darf – hier schlägt die doch sehr locke­re Defi­ni­ti­on des HTML zu. ↩

3. Ich lie­be die­se Funk­ti­on, daher suche ich häu­fig nach Mög­lich­kei­ten, mir die Arbeit zu erleich­tern nach dem Prin­zip des „Wri­te-once-publish-ever­y­whe­re“. ↩