Manual als Wiki: Schneller als sein Schatten

Hand­buch, Manu­al, Anlei­tun­gen aller Art: Wie Inno­va­ti­on auch besteht die Doku­men­ta­ti­on tech­ni­schen Wis­sens aus 10% Inspi­ra­ti­on und 90% Tran­spi­ra­ti­on.

Damit die Doku­men­ta­ti­on Hand und Fuß hat, genügt es nicht, die vor­han­de­nen Infor­ma­tio­nen zusam­men­zu­rüh­ren, auf­zu­hüb­schen und dann mög­lichst rasch „Fer­tig!“ zu rufen. Im Gegen­teil, mit die­ser Vor­ge­hens­wei­se ist das Schei­tern vor­pro­gram­miert. Für eine Doku­men­ta­ti­on muss zunächst ein Kon­zept vor­lie­gen. Dazu gehört auch Inspi­ra­ti­on und Krea­ti­vi­tät bei der Lösung der grund­le­gen­den Fra­gen zum Pro­zess und zur Ein­bet­tung des Pro­zes­ses in das gesam­te Pro­jekt.

Für einen erfah­re­nen Tech­ni­k­re­dak­teur soll­te die­ser Teil aller­dings kei­ne Stra­fe sein, son­dern eine Inspi­ra­ti­on, denn an die­ser Stel­le ist kei­ne Doku­men­ta­ti­on wie die ande­re – jedes Pro­jekt ver­langt nach Anpas­sun­gen, um das Ziel mög­lichst effi­zi­ent und effek­tiv zu errei­chen (sie­he auch Von Kano­nen und Spat­zen: Effi­zi­enz in der Doku­men­ta­ti­on).

https://​www​.rea​dit​-dtp​.de/​2​0​1​8​/​0​4​/​v​o​n​-​k​a​n​o​n​e​n​-​u​n​d​-​s​p​a​t​z​e​n​-​e​f​f​i​z​i​e​n​z​-​i​n​-​d​e​r​-​d​o​k​u​m​e​n​t​a​t​i​o​n​/​N​ach dem inspi­rie­ren­den Teil der krea­ti­ven Pro­blem­lö­sung kommt die müh­sa­me Arbeit: das Auf­schrei­ben, Sich­ten und Gewich­ten der Infor­ma­ti­on. Das ist dann der Abschnitt, der den Tech­ni­k­re­dak­teur manch­mal zur Ver­zweif­lung treibt, wenn Pro­dukt­lei­ter sich in den redak­tio­nel­len Pro­zess ein­mi­schen oder ein­fach nicht ein­se­hen wol­len, dass die Preis­lis­ten oder AGBs nun defi­ni­tiv nicht Teil der Doku­men­ta­ti­on sind. Wenn Infor­ma­tio­nen plötz­lich auf dem Tisch lie­gen, die man bes­ser schon frü­her gekannt hät­te.

Oder wenn fach­frem­de Per­so­nen (als „Stake­hol­der“) ver­lan­gen, die Doku­men­ta­ti­on müs­se mit dem Pro­gramm XYZ geschrie­ben wer­den, weil sie kein ande­res ken­nen. Noch dazu, wenn man als Redak­teur dar­auf­hin stun­den­lang mit For­ma­tie­rungs­auf­ga­ben beschäf­tigt wird, die sich mit dem Pro­gramm gar nicht umset­zen las­sen oder zu end­lo­ser Hand­ar­beit füh­ren und Zeit kos­ten – Zeit, die man auf den Inhalt bes­ser ver­wen­det hät­te.¹

Manch­mal han­delt es sich auch um Doku­men­ta­tio­nen, die inner­halb des Unter­neh­mens oder der Orga­ni­sa­ti­on ver­wen­det wer­den sol­len und selbst dort nur an eine bestimm­te Grup­pe, die dafür aber inter­na­tio­nal ver­streut ist. Sie müs­sen kei­ne gesetz­li­chen oder nor­ma­ti­ven Anfor­de­run­gen erfül­len, son­dern sind Teil der Pro­jekt­do­ku­men­ta­ti­on. Bei mul­ti­na­tio­na­len Unter­neh­men kommt das sogar häu­fig vor: die Pro­dukt­lei­ter sit­zen in Deutsch­land, die Pro­gram­mie­rer in Tsche­chi­en, die Tech­ni­ker in Isra­el und die Anwen­der des glei­chen Kon­zerns in Chi­na.

Glo­ba­li­sie­rung

Die­se Grup­pen arbei­ten je nach Pro­jekt eine gewis­se Zeit zusam­men, dann wer­den Mit­ar­bei­ter abge­zo­gen, um an einem neu­en Pro­jekt zu arbei­ten wäh­rend die ver­blie­be­nen Mit­ar­bei­ter um neue Kol­le­gen ergänzt wer­den. Das ist nicht nur eine orga­ni­sa­to­ri­sche Her­aus­for­de­rung für die Pro­jekt­lei­tung, es ist auch eine infor­ma­ti­ons­tech­ni­sche Her­aus­for­de­rung für die Grup­pe. Denn sobald ein Team­mit­glied nicht mehr dabei ist, benö­tigt es kei­ne Infor­ma­tio­nen mehr zu dem Pro­jekt.² Der Pro­jekt­lei­ter ent­zieht die­sem Mit­glied die Zugriffs­rech­te auf die Infor­ma­tio­nen des Pro­jekts. Die neu­en Mit­glie­der erhal­ten dafür die ent­spre­chen­den Berech­ti­gun­gen und sind ihrer­seits gefor­dert, sich so schnell wie mög­lich auf den aktu­el­len Infor­ma­ti­ons­stand zu brin­gen, ohne dafür durch die Abtei­lun­gen zu pil­gern und Mit­ar­bei­ter zu suchen, die sich mit dem The­ma aus­ken­nen.

Mit Tot­holz­aus­ga­ben und ihren digi­ta­len Pen­dants kommt man hier nicht mehr weit. Doku­men­te, die papier­zen­triert (d.h. mit einer Text­ver­ar­bei­tung geschrie­ben und gelay­outet) erstellt und dann digi­ta­li­siert wur­den, sind in dem Moment ver­al­tet, in dem sie publi­ziert und damit vom Infor­ma­ti­ons­fluss „abge­na­belt“ wer­den. Die Fra­ge „Wer hat wann wo etwas geän­dert?“ führt schon nach weni­gen Wochen dazu, dass kei­ner mehr weiß, ob er noch den aktu­el­len Stand ver­wen­det.

Die Pro­ble­ma­tik ist vor allem bei Soft­ware­pro­jek­ten schon län­ger bekannt, wenn nicht mehr Bau­tei­le phy­sisch bewegt wer­den müs­sen, son­dern nur noch „Builds“ auf dem Ser­ver bereit gestellt wer­den: die Ent­wick­ler auf der einen Sei­te des Glo­bus kom­pi­lie­ren abends eine neue Ver­si­on der Soft­ware, die die Tes­ter auf der ande­ren Sei­te am Mor­gen down­loa­den und instal­lie­ren. Die gefun­de­nen Feh­ler und Pro­ble­me wer­den in eine Soft­ware ein­ge­tra­gen, die die Pro­gram­mie­rer regel­mä­ßig infor­miert und anste­hen­de Auf­ga­ben ver­teilt.

Auch die Auf­lö­sung von Raum und Zeit ist Teil der Arbeits­welt des 21. Jahr­hun­derts. Sie ver­langt vom Ein­zel­nen eine Neu­jus­tie­rung sei­ner Berufs­vor­stel­lung und ‑tätig­keit eben­so, wie sie von einer glo­ba­li­sier­ten Gesell­schaft ver­langt, den Teil­neh­mern ein ent­spre­chen­des men­ta­les Rüst­zeug an die Hand zu geben.

In die­sem unun­ter­bro­che­nen Wel­len­spiel der Pro­jekt­in­for­ma­tio­nen muss auch der Tech­ni­k­re­dak­teur schwim­men, da er ja Teil des Teams ist. Ein Pro­dukt, das nie wirk­lich fer­tig ist, eine Soft­ware, die regel­mä­ßig aktua­li­siert wer­den muss – das bedeu­tet auch, das die Doku­men­ta­ti­on abschnitts­wei­se aus­ge­lie­fert wird. Und die­se Abschnit­te kön­nen rela­tiv kurz sein: von weni­gen Wochen bis zu weni­gen Stun­den wer­den Aktua­li­sie­rungs­zy­klen ange­setzt, die mit her­kömm­li­cher Soft­ware zur Text­ver­ar­bei­tung nicht zu bewäl­ti­gen sind.

Wiki

Tech­ni­k­re­dak­teu­re den­ken oft noch zu line­ar im Infor­ma­ti­ons­pro­zess: Erst gibt es eine Pro­dukt­ent­wick­lung, dann wird das Pro­dukt erstellt, dann doku­men­tiert, über­setzt und zum Schluss wird die Doku­men­ta­ti­on zusam­men mit dem Pro­dukt gelie­fert. Nach einem hal­ben Jahr oder län­ger gibt es dann ein Update oder eine Nach­rüs­tung des Pro­dukts, die Doku­men­ta­ti­on wird ergänzt, über­setzt und zusam­men mit der Aktua­li­sie­rung gelie­fert.

Das ist nicht ganz falsch – nur haben sich die­se Fer­ti­gungs­ab­schnit­te inein­an­der ver­scho­ben (das lässt sich an den Gantt-Dia­gram­men der Pro­jekt­lei­ter able­sen). Aus Zeit- und Orga­ni­sa­ti­ons­grün­den über­lap­pen sich die Pro­zes­se oder lau­fen par­al­lel mit einem gemein­sa­men Ziel­zeit­punkt. Das erfor­dert Kom­pro­mis­se auch in der Doku­men­ta­ti­on. Kor­rek­tur­pha­sen wer­den gestrafft, Lese­rech­te aus­ge­wei­tet und Mit­spra­che­rech­te klar defi­niert. Das führt auch kon­se­quen­ter­wei­se zu Ver­än­de­run­gen im Tätig­keits­feld des Tech­ni­k­re­dak­teurs.

Natür­lich benö­tigt man dazu zunächst ein Kon­zept, denn auch als Tech­ni­k­re­dak­teur kann man nicht alle Bespre­chungs­no­ti­zen und Feh­ler­mel­dun­gen oder Spe­zi­fi­ka­tio­nen unge­fil­tert wei­ter­ge­ben. Die Infor­ma­ti­on muss auf­be­rei­tet wer­den – inhalt­lich und struk­tu­rell. Und sie muss schnell anpass­bar sein. (Der But­ton ist jetzt rechts? Screen­shot erstel­len, uploa­den, refe­ren­zie­ren und publi­zie­ren ist in weni­gen Minu­ten erle­digt. – Die Bestell­num­mer ist neu? Anpas­sen, spei­chern, fer­tig.)

Das ist ein kla­rer Fall für Online-Doku­men­ta­ti­on. Aber kei­ne, bei der die Anlei­tung erst geschrie­ben, kom­pi­liert und zum Schluss publi­ziert wird, son­dern ein Wiki: Text rein, Bild rein, refe­ren­zie­ren – fer­tig.

Die Vor­aus­set­zung ist aller­dings, dass man nicht nur ein Kon­zept hat (s.o.), son­dern sich auch ein paar Syn­tax­re­geln aneig­net, die nicht unbe­dingt intui­tiv sind, aber dafür wenig Raum für „unsau­be­res“ Arbei­ten las­sen. Und ein paar grund­le­gen­de HTML-Kennt­nis­se sind auch ganz prak­tisch, denn in einem Wiki gel­ten die Regeln des Inter­nets:

• Es gibt Hyper­links, aber kei­ne Quer­ver­wei­se
• Es gibt Sei­ten, aber kei­ne Sei­ten­zah­len
• Es gibt Über­schrif­ten, aber kei­ne Über­schrift­num­me­rie­rung

Kurz: alles, was eine Doku­men­ta­ti­on line­ar macht, gibt’s nicht. Wir bewe­gen uns im Hyper­space.

Lost in Hyper­space?

Damit man sich und den Leser nicht in die­sem ver­meint­li­chen Cha­os ver­liert, ver­langt ein sol­cher Sta­pel gleich­ran­gi­ger Datei­en nicht nach einer Über­schrif­ten­hier­ar­chie (das wäre wie­der papier-zen­triert), son­dern nach einer Lis­ten­hier­ar­chie.

Vor­aus­set­zun­gen

Je nach Wiki (es gibt meh­re­re, hier neh­men wir red­mi­ne, das vor allem für die Pro­jekt­ver­wal­tung geeig­net ist und damit die Mög­lich­keit zur Pro­jekt­do­ku­men­ta­tio­nen gleich mit­bringt) muss zunächst ein Doku­men­ta­ti­ons­pro­jekt ein­ge­rich­tet wer­den. Das darf nur der Admi­nis­tra­tor, denn die­ser legt auch die Zugriffs­rech­te fest.

Zu Beginn ist auch eine Über­sicht der Wiki-spe­zi­fi­schen Syn­tax­re­geln hilf­reich, auch wenn sie sich oft nur mar­gi­nal unter­schei­den.

Mer­ke: Wiki bedeu­tet Tip­pen, nicht Maus­ren­nen.

Ord­nung in Lis­ten

Ein Inhalts­ver­zeich­nis ist im Grun­de nur eine Lis­te der Über­schrif­ten (und damit Topics, sie­he auch Topics: Infor­ma­ti­ons­häpp­chen hirn­ge­recht ser­vie­ren). Da alle Sei­ten eines Wikis zwar bestimm­ten Sei­ten zuge­ord­net wer­den kön­nen und soll­ten (was für die „Bread­crumb-Navi­ga­ti­on“ wich­tig ist, um dem Leser zu sagen, wo er sich gera­de befin­det), erstel­len Wikis zwar auto­ma­tisch Über­sich­ten – aber sor­tie­ren sie nicht nach der Vor­stel­lung des Redak­teurs. Lis­ten mit Hyper­links sind hier viel fle­xi­bler.

Das geht so:

1. Man öff­net die Start­sei­te des Wikis und wählt „Bear­bei­ten“.
2. Jetzt kommt die Syn­tax mit dop­pel­ten ecki­gen Klam­mern, die einen Hyper­link auf eine Sei­te erzeugt, die es noch nicht gibt (spä­tes­tens jetzt weiß man, wozu das Kon­zept wich­tig ist…).
3. Spei­chern und kon­trol­lie­ren.

Sei­ten bas­teln

Ab sofort ist es ein­fach: Wir müs­sen nur noch auf den Hyper­link kli­cken (oder tip­pen, denn wir arbei­ten ja im Brow­ser, und das geht auch mit einem Tablet oder Smart­phone) und die Sei­te wird auto­ma­tisch erstellt und die Über­schrift über­nom­men.

Aus einem ein­fa­chen Text…

… wird nach dem Spei­chern dann das:

Der Zau­ber aller­dings ist nicht die (tri­via­le) Text­an­zei­ge, son­dern die Funk­tio­nen, die im Hin­ter­grund mit­lau­fen:

• Die Sei­ten kön­nen mit Benach­rich­ti­gun­gen ver­se­hen wer­den („Watch“), damit das Wiki den Benut­zer benach­rich­tigt, sobald die Sei­te geän­dert wur­de.
• Die Sei­ten wer­den ver­sio­niert („Histo­ry“), um nach­ver­fol­gen zu kön­nen, wel­che Inhal­te von wel­chem Benut­zer zu wel­chem Zeit­punkt geän­dert wur­den.
• Die Sei­ten kön­nen für die Bear­bei­tung gesperrt wer­den („Lock“, vor allem in grö­ße­ren Pro­jek­ten wich­tig)
• Die Sei­ten kön­nen als PDF expor­tiert und damit gedruckt wer­den – aller­dings nur in einem wenig anspre­chen­den Lay­out (was ja auch nicht unbe­dingt das Ziel ist)
• Die Sei­ten kön­nen als (sta­ti­sches) HTML expor­tiert wer­den, um sie bei­spiels­wei­se an Außen­ste­hen­de als E‑Mail zu ver­schi­cken oder in eine Text­da­tei zu kopie­ren

Außer­dem

Abhän­gig vom Wiki gibt es noch wei­te­re Funk­tio­nen, die vor allem für die Tech­ni­sche Doku­men­ta­ti­on wich­tig sind:

• Die Wie­der­ver­wen­dung von Inhal­ten (als gan­ze Sei­ten mit belie­bi­gen Inhal­ten) bei­spiels­wei­se mit „{{include(Seitenname)}}“
• Das Anle­gen von Inhalts­ver­zeich­nis­sen inner­halb einer Sei­ten mit „{{TOC}}“
• Das Anle­gen von Tabel­len – das ist bei jeder Syn­tax unter­schied­lich, aber oft mit „|Zel­le 1|Zelle 2|“
• Die Ver­wen­dung von Bil­dern und Gra­fi­ken sowohl als ver­link­te Datei­en (z.B. PDF) als auch direkt im Text
• Die Ver­lin­kun­gen auf Doku­men­te, Inter­net­sei­ten und ande­re Pro­jek­te ein­schließ­lich Text­an­ker

Schluss­be­mer­kung

Wenn man sich als Tech­ni­k­re­dak­teur vor Augen führt, dass man in der Tech­nik­do­ku­men­ta­ti­on oft für stumpf­sin­ni­ge Tätig­kei­ten wie die For­ma­tie­rung oder die Nach­ver­fol­gung von Infor­ma­ti­ons­pro­zes­sen („Wann wur­de die­se Tabel­le aktua­li­siert?“) häu­fig Zeit opfert, die auf Kos­ten der Qua­li­tät des Inhalts gehen, spricht kaum noch etwas gegen die Nut­zung eines Wikis für die Erstel­lung.

Man muss nur das Papier los­las­sen…³

---

Wer das unver­bind­lich aus­pro­bie­ren will ohne gleich die hal­be IT-Abtei­lung in den Wahn­sinn zu trei­ben (oder die Pro­jekt­lei­tung auf den Geschmack zu brin­gen): Es gibt fer­ti­ge Pake­te, die sich lokal oder in der Cloud tes­ten las­sen, bei­spiels­wei­se von Bit­na­mi.

---

1. Lachen Sie nicht, aber es gibt Kun­den, die ihre Doku­men­ta­ti­on mit Power­Point erstellt haben möch­ten – ein­schließ­lich Inhalts­ver­zeich­nis… ↩

2. Damit soll nicht nur die Infor­ma­ti­on geschützt wer­den, son­dern vor allem auch das (ehe­ma­li­ge) Mit­glied vor Infor­ma­tio­nen, die es nicht mehr benö­tigt. ↩

3. Ja ich weiß, jetzt schreit der Nächs­te „Maschi­nen­richt­li­nie!“, aber ers­tens steht nir­gend­wo, dass Papier über­all erfor­der­lich ist, noch kann man mit Wikis allen Anfor­de­run­gen an eine End­nut­zer­do­ku­men­ta­ti­on gerecht wer­den. Das ist aller­dings bei vie­len Doku­men­ten ers­tens gar nicht erfor­der­lich – und zwei­tens erfül­len dies auch vie­le papier­zen­trier­te Doku­men­ta­tio­nen nicht. ↩