Technische Dokumentation: Schlank durchs Jahr

Ja, auch Tech­ni­sche Doku­men­ta­tio­nen besit­zen eine gewis­se Eitel­keit und wol­len ganz ger­ne eine sport­lich-schlan­ke Figur abge­ben. Denn das ver­lei­tet nicht nur die Nut­zer zum Hin­schau­en, son­dern nutzt auch dem Ziel der Infor­ma­ti­ons­ver­mitt­lung.

Jeder Redak­teur, der eine Doku­men­ta­ti­on über Jah­re hin­weg betreut und zahl­rei­che Ände­run­gen, Aktua­li­sie­run­gen und Ergän­zun­gen dar­an durch­ge­führt hat, weiß um das Pro­blem: Auch die durch­dach­tes­te und dis­zi­pli­nier­tes­te Arbeits­wei­se ver­hin­dert nicht, dass die Doku­men­ta­ti­on Speck ansetzt: Hier mal ein hoch­auf­lö­sen­des Bild dazu, dort eine Vari­an­te oder Opti­on ein­ge­fügt, viel­leicht noch im Zeit­druck die Begriff­lich­keit etwas nach­läs­si­ger ange­gan­gen und ent­spre­chend Red­un­danz erzeugt – und schon wer­den aus 5 MB auf ein­mal 10 MB und aus „mal schnell ändern“ wer­den zwei Tage.

Nun kann es nicht das Ziel jeder Doku­men­ta­ti­on sein, einen benei­dens­wer­ten „Wasch­brett­bauch“ zur Schau zu stel­len, denn der Auf­wand dazu ist enorm (wie im All­tag halt auch) – und erfor­dert vom Tech­ni­schen Redak­teur schier über­mensch­li­che Kräf­te und Dis­zi­plin, sich gegen die wohl­mei­nen­den Wün­sche der SMEs zur Wehr zu set­zen und kei­ner Ver­lo­ckung nach­zu­ge­ben, viel­leicht nicht doch noch eine Tabel­le oder Lis­te oder neue Bil­der ein­zu­bau­en.¹

Trotz der Vor­ah­nung, dass jeder Zusatz nur sehr schwer nach­träg­lich wie­der zu ent­fer­nen ist, lässt man halt dann doch mal Fün­fe gra­de sein und fügt sich den Ideen und Vor­schlä­gen, die sich im Lau­fe der Jah­re so ansam­meln.²

Das böse Erwa­chen kommt erst viel spä­ter:

• Hyper­links und Quer­ver­wei­se, die ins Lee­re füh­ren
• Bil­der und Screen­shots, von denen Jah­re spä­ter kein Mensch weiß, wozu sie über­haupt da sind und sowie­so nur eine ver­al­te­ten Stand abbil­den
• Lade­zei­ten, die jedem Leser mit einem durch­schnitt­li­chen Tarif den Schweiß auf die Stirn trei­ben
• Anlei­tun­gen in Rom­an­stär­ke, bei denen allei­ne die Ein­lei­tung (mit freund­li­chem Gruß aus der Mar­ke­ting­ab­tei­lung) nicht unter 10 Sei­ten und 12 Bil­dern daher kommt
• explo­die­ren­de Kos­ten bei der Über­set­zung und Loka­li­sie­rung

Ergo: So wie sich eine unge­sun­de Lebens­füh­rung erst vie­le Jah­re spä­ter bemerk­bar macht, legt sich die Doku­men­ta­ti­on im Lau­fe weni­ger Jah­re ein „Hüft­gold“ zu, das nur mit einem enor­men Auf­wand wie­der eini­ger­ma­ßen in Form zu bekom­men ist.

Aber genug der Ana­lo­gien…

Um dau­er­haft eine Doku­men­ta­ti­on auf Kurs zu hal­ten, benö­tigt man eigent­lich nur zwei Din­ge: eine Vor­stel­lung vom erreich­ba­ren Ziel – und das rich­ti­ge Werk­zeug.

Fla­re und Ana­ly­zer

Mei­ne bevor­zug­te Kom­bi­na­ti­on als Nut­zer von Mad­Cap Fla­re ist der zusätz­li­che Ana­ly­zer³. Dadurch, dass in Fla­re die Tex­te als Topics ange­legt sind, fin­den sich red­un­dan­te Stel­len zwar schnell, aber mit Ana­ly­zer geht es noch schnel­ler: Ana­ly­zer schlägt nach dem Durch­lauf vor, iden­ti­sche For­mu­lie­run­gen als Snip­pets anzu­le­gen. Damit wer­den ein­mal erstell­te Text­bau­stei­ne an meh­re­ren Stel­len wie­der­ver­wend­bar ein­ge­setzt. Das kann man zwar machen – man kann sich aber auch die Fra­ge stel­len, ob ein mehr­fach ver­wen­de­ter Text nicht mög­li­cher­wei­se auf Red­un­danz hin­deu­tet (Aus­nah­me: Sicher­heits­hin­wei­se). Die Doku­men­ta­ti­on ist ja kei­ne Rum­pel­kam­mer – und jede Infor­ma­ti­on, die mehr­fach vor­liegt, führt nicht nur zu Ver­wir­rung, son­dern auch zu mehr Pfle­ge.

Eine her­vor­ra­gen­de Funk­ti­on ist die Suche nach nicht benutz­ten (aka refe­ren­zier­ten) Datei­en. Nicht refe­ren­zier­te Bil­der und Datei­en, auf deren Inhalt nir­gend­wo ver­wie­sen wird, sind über­flüs­sig.⁴.

Nach der Ana­ly­se lie­fert das Pro­gramm alle mög­li­chen Schwach­stel­len, die sich nun ganz ein­fach behe­ben las­sen. Um den Auf­wand gering zu hal­ten, fängt man am Bes­ten damit an, die feh­len­den Datei­en ein­zu­bau­en, die das Pro­gramm moniert. Danach löscht man die nicht benutz­ten Datei­en.

Ado­be InDe­sign

Es geht teil­wei­se aber auch mit InDe­sign: Die Funk­ti­on, Datei­en für den Druck bereit­zu­stel­len, ist zwar ange­sichts der zuneh­men­den Online-Publi­ka­tio­nen etwas merk­wür­dig, soll sie doch eine feh­ler­freie Druck­aus­ga­be sicher­stel­len – man kann sie aber auch anders nut­zen. Denn auch für die Dru­cke­rei ist es wenig hilf­reich, Bil­der zu erhal­ten, die nicht gedruckt wer­den. Die Bereit­stel­lung als „Package“-Datei eines Buches zieht des­we­gen nur die Bil­der, Schrif­ten und sons­ti­gen infor­ma­tio­nen zusam­men, die auch refe­ren­ziert wer­den. Die­se wer­den dann in einen neu­en Ord­ner gepackt und ggf. die Ver­wei­se ange­passt. Dadurch ent­steht eine in sich geschlos­se­ne Kopie des Ori­gi­nals, des­sen Infor­maio­nen mög­li­cher­wei­se irgend­wo im Datei­sys­tem ver­steckt sind.

Danach kann man die­se Pake­te wei­ter­ver­wen­den und behält dadurch nur die tat­säch­lich benutz­ten Daten.⁵ Aller­dings funk­tio­niert das nur für Bil­der und Gra­fi­ken (und Zei­chen­sät­ze), denn InDe­sign ana­ly­siert den Inhalt nicht auf Red­un­dan­zen. Dafür ist das Pro­gramm ja auch nicht gemacht …

War­nung

Ein Hin­weis bevor Sie jetzt mutig den Früh­jahrs­putz ange­hen: Ohne regel­mä­ßi­ge Back­ups soll­ten Sie sich nicht ans Löschen machen. Sowas kann böse enden.

Soll­ten sie noch ande­re Mög­lich­kei­ten ken­nen, wie man die Doku­men­ta­ti­on schlank hal­ten kann: Nur zu!

1. Gemeint sind Bil­der und Tabel­len, die meist aus ganz ande­ren Grün­den erstellt wur­den und in der Doku­men­ta­ti­on aus Bequem­lich­keit recy­celt wer­den. Sie pas­sen meist nicht zur Inten­ti­on der Kun­den­do­ku­men­ta­ti­on. ↩

2. Bei Selbst­stän­di­gen kommt noch dazu, dass der Auf­wand, der getrie­ben wer­den muss, um eine Doku­men­ta­ti­on schlank zu hal­ten, oft nicht hono­riert wird: man sieht es näm­lich nicht. ↩

3. Ich habe ihn hier schon beschrei­ben: Mad­Cap Ana­ly­zer: Gabel­stap­ler für Online­hil­fen. ↩

4. Fla­re lie­fert bei der Publi­ka­ti­on zwar nur die Bil­der und Topics, die auch wirk­lich refe­ren­ziert sind, aber die ande­ren blei­ben trotz­dem als „Lei­chen“ im Pro­jekt­ord­ner und trei­ben den Pfle­ge­auf­wand nach oben. ↩

5. Erfah­rungs­ge­mäß ist der Gra­fik­ord­ner immer der „dicks­te“. ↩