Handbuch, Manual, Anleitungen aller Art: Wie Innovation auch besteht die Dokumentation technischen Wissens aus 10% Inspiration und 90% Transpiration.
Damit die Dokumentation Hand und Fuß hat, genügt es nicht, die vorhandenen Informationen zusammenzurühren, aufzuhübschen und dann möglichst rasch „Fertig!“ zu rufen. Im Gegenteil, mit dieser Vorgehensweise ist das Scheitern vorprogrammiert. Für eine Dokumentation muss zunächst ein Konzept vorliegen. Dazu gehört auch Inspiration und Kreativität bei der Lösung der grundlegenden Fragen zum Prozess und zur Einbettung des Prozesses in das gesamte Projekt.
Für einen erfahrenen Technikredakteur sollte dieser Teil allerdings keine Strafe sein, sondern eine Inspiration, denn an dieser Stelle ist keine Dokumentation wie die andere – jedes Projekt verlangt nach Anpassungen, um das Ziel möglichst effizient und effektiv zu erreichen (siehe auch Von Kanonen und Spatzen: Effizienz in der Dokumentation).
Nach dem inspirierenden Teil der kreativen Problemlösung kommt die mühsame Arbeit: das Aufschreiben, Sichten und Gewichten der Information. Das ist dann der Abschnitt, der den Technikredakteur manchmal zur Verzweiflung treibt, wenn Produktleiter sich in den redaktionellen Prozess einmischen oder einfach nicht einsehen wollen, dass die Preislisten oder AGBs nun definitiv nicht Teil der Dokumentation sind. Wenn Informationen plötzlich auf dem Tisch liegen, die man besser schon früher gekannt hätte.
Oder wenn fachfremde Personen (als „Stakeholder“) verlangen, die Dokumentation müsse mit dem Programm XYZ geschrieben werden, weil sie kein anderes kennen. Noch dazu, wenn man als Redakteur daraufhin stundenlang mit Formatierungsaufgaben beschäftigt wird, die sich mit dem Programm gar nicht umsetzen lassen oder zu endloser Handarbeit führen und Zeit kosten – Zeit, die man auf den Inhalt besser verwendet hätte.1
Manchmal handelt es sich auch um Dokumentationen, die innerhalb des Unternehmens oder der Organisation verwendet werden sollen und selbst dort nur an eine bestimmte Gruppe, die dafür aber international verstreut ist. Sie müssen keine gesetzlichen oder normativen Anforderungen erfüllen, sondern sind Teil der Projektdokumentation. Bei multinationalen Unternehmen kommt das sogar häufig vor: die Produktleiter sitzen in Deutschland, die Programmierer in Tschechien, die Techniker in Israel und die Anwender des gleichen Konzerns in China.
Globalisierung
Diese Gruppen arbeiten je nach Projekt eine gewisse Zeit zusammen, dann werden Mitarbeiter abgezogen, um an einem neuen Projekt zu arbeiten während die verbliebenen Mitarbeiter um neue Kollegen ergänzt werden. Das ist nicht nur eine organisatorische Herausforderung für die Projektleitung, es ist auch eine informationstechnische Herausforderung für die Gruppe. Denn sobald ein Teammitglied nicht mehr dabei ist, benötigt es keine Informationen mehr zu dem Projekt.2 Der Projektleiter entzieht diesem Mitglied die Zugriffsrechte auf die Informationen des Projekts. Die neuen Mitglieder erhalten dafür die entsprechenden Berechtigungen und sind ihrerseits gefordert, sich so schnell wie möglich auf den aktuellen Informationsstand zu bringen, ohne dafür durch die Abteilungen zu pilgern und Mitarbeiter zu suchen, die sich mit dem Thema auskennen.
Mit Totholzausgaben und ihren digitalen Pendants kommt man hier nicht mehr weit. Dokumente, die papierzentriert (d.h. mit einer Textverarbeitung geschrieben und gelayoutet) erstellt und dann digitalisiert wurden, sind in dem Moment veraltet, in dem sie publiziert und damit vom Informationsfluss „abgenabelt“ werden. Die Frage „Wer hat wann wo etwas geändert?“ führt schon nach wenigen Wochen dazu, dass keiner mehr weiß, ob er noch den aktuellen Stand verwendet.
Die Problematik ist vor allem bei Softwareprojekten schon länger bekannt, wenn nicht mehr Bauteile physisch bewegt werden müssen, sondern nur noch „Builds“ auf dem Server bereit gestellt werden: die Entwickler auf der einen Seite des Globus kompilieren abends eine neue Version der Software, die die Tester auf der anderen Seite am Morgen downloaden und installieren. Die gefundenen Fehler und Probleme werden in eine Software eingetragen, die die Programmierer regelmäßig informiert und anstehende Aufgaben verteilt.
Auch die Auflösung von Raum und Zeit ist Teil der Arbeitswelt des 21. Jahrhunderts. Sie verlangt vom Einzelnen eine Neujustierung seiner Berufsvorstellung und -tätigkeit ebenso, wie sie von einer globalisierten Gesellschaft verlangt, den Teilnehmern ein entsprechendes mentales Rüstzeug an die Hand zu geben.
In diesem ununterbrochenen Wellenspiel der Projektinformationen muss auch der Technikredakteur schwimmen, da er ja Teil des Teams ist. Ein Produkt, das nie wirklich fertig ist, eine Software, die regelmäßig aktualisiert werden muss – das bedeutet auch, das die Dokumentation abschnittsweise ausgeliefert wird. Und diese Abschnitte können relativ kurz sein: von wenigen Wochen bis zu wenigen Stunden werden Aktualisierungszyklen angesetzt, die mit herkömmlicher Software zur Textverarbeitung nicht zu bewältigen sind.
Wiki
Technikredakteure denken oft noch zu linear im Informationsprozess: Erst gibt es eine Produktentwicklung, dann wird das Produkt erstellt, dann dokumentiert, übersetzt und zum Schluss wird die Dokumentation zusammen mit dem Produkt geliefert. Nach einem halben Jahr oder länger gibt es dann ein Update oder eine Nachrüstung des Produkts, die Dokumentation wird ergänzt, übersetzt und zusammen mit der Aktualisierung geliefert.
Das ist nicht ganz falsch – nur haben sich diese Fertigungsabschnitte ineinander verschoben (das lässt sich an den Gantt-Diagrammen der Projektleiter ablesen). Aus Zeit- und Organisationsgründen überlappen sich die Prozesse oder laufen parallel mit einem gemeinsamen Zielzeitpunkt. Das erfordert Kompromisse auch in der Dokumentation. Korrekturphasen werden gestrafft, Leserechte ausgeweitet und Mitspracherechte klar definiert. Das führt auch konsequenterweise zu Veränderungen im Tätigkeitsfeld des Technikredakteurs.
Natürlich benötigt man dazu zunächst ein Konzept, denn auch als Technikredakteur kann man nicht alle Besprechungsnotizen und Fehlermeldungen oder Spezifikationen ungefiltert weitergeben. Die Information muss aufbereitet werden – inhaltlich und strukturell. Und sie muss schnell anpassbar sein. (Der Button ist jetzt rechts? Screenshot erstellen, uploaden, referenzieren und publizieren ist in wenigen Minuten erledigt. – Die Bestellnummer ist neu? Anpassen, speichern, fertig.)
Das ist ein klarer Fall für Online-Dokumentation. Aber keine, bei der die Anleitung erst geschrieben, kompiliert und zum Schluss publiziert wird, sondern ein Wiki: Text rein, Bild rein, referenzieren – fertig.
Die Voraussetzung ist allerdings, dass man nicht nur ein Konzept hat (s.o.), sondern sich auch ein paar Syntaxregeln aneignet, die nicht unbedingt intuitiv sind, aber dafür wenig Raum für „unsauberes“ Arbeiten lassen. Und ein paar grundlegende HTML-Kenntnisse sind auch ganz praktisch, denn in einem Wiki gelten die Regeln des Internets:
- Es gibt Hyperlinks, aber keine Querverweise
- Es gibt Seiten, aber keine Seitenzahlen
- Es gibt Überschriften, aber keine Überschriftnummerierung
Kurz: alles, was eine Dokumentation linear macht, gibt’s nicht. Wir bewegen uns im Hyperspace.
Lost in Hyperspace?
Damit man sich und den Leser nicht in diesem vermeintlichen Chaos verliert, verlangt ein solcher Stapel gleichrangiger Dateien nicht nach einer Überschriftenhierarchie (das wäre wieder papier-zentriert), sondern nach einer Listenhierarchie.
Voraussetzungen
Je nach Wiki (es gibt mehrere, hier nehmen wir redmine, das vor allem für die Projektverwaltung geeignet ist und damit die Möglichkeit zur Projektdokumentationen gleich mitbringt) muss zunächst ein Dokumentationsprojekt eingerichtet werden. Das darf nur der Administrator, denn dieser legt auch die Zugriffsrechte fest.
Zu Beginn ist auch eine Übersicht der Wiki-spezifischen Syntaxregeln hilfreich, auch wenn sie sich oft nur marginal unterscheiden.
Merke: Wiki bedeutet Tippen, nicht Mausrennen.
Ordnung in Listen
Ein Inhaltsverzeichnis ist im Grunde nur eine Liste der Überschriften (und damit Topics, siehe auch Topics: Informationshäppchen hirngerecht servieren). Da alle Seiten eines Wikis zwar bestimmten Seiten zugeordnet werden können und sollten (was für die „Breadcrumb-Navigation“ wichtig ist, um dem Leser zu sagen, wo er sich gerade befindet), erstellen Wikis zwar automatisch Übersichten – aber sortieren sie nicht nach der Vorstellung des Redakteurs. Listen mit Hyperlinks sind hier viel flexibler.
Das geht so:
Man öffnet die Startseite des Wikis und wählt „Bearbeiten“.- Jetzt kommt die Syntax mit doppelten eckigen Klammern, die einen Hyperlink auf eine Seite erzeugt, die es noch nicht gibt (spätestens jetzt weiß man, wozu das Konzept wichtig ist…).
- Speichern und kontrollieren.
Seiten basteln
Ab sofort ist es einfach: Wir müssen nur noch auf den Hyperlink klicken (oder tippen, denn wir arbeiten ja im Browser, und das geht auch mit einem Tablet oder Smartphone) und die Seite wird automatisch erstellt und die Überschrift übernommen.
Aus einem einfachen Text…
… wird nach dem Speichern dann das:
Der Zauber allerdings ist nicht die (triviale) Textanzeige, sondern die Funktionen, die im Hintergrund mitlaufen:
- Die Seiten können mit Benachrichtigungen versehen werden („Watch“), damit das Wiki den Benutzer benachrichtigt, sobald die Seite geändert wurde.
- Die Seiten werden versioniert („History“), um nachverfolgen zu können, welche Inhalte von welchem Benutzer zu welchem Zeitpunkt geändert wurden.
- Die Seiten können für die Bearbeitung gesperrt werden („Lock“, vor allem in größeren Projekten wichtig)
- Die Seiten können als PDF exportiert und damit gedruckt werden – allerdings nur in einem wenig ansprechenden Layout (was ja auch nicht unbedingt das Ziel ist)
- Die Seiten können als (statisches) HTML exportiert werden, um sie beispielsweise an Außenstehende als E-Mail zu verschicken oder in eine Textdatei zu kopieren
Außerdem
Abhängig vom Wiki gibt es noch weitere Funktionen, die vor allem für die Technische Dokumentation wichtig sind:
- Die Wiederverwendung von Inhalten (als ganze Seiten mit beliebigen Inhalten) beispielsweise mit „{{include(Seitenname)}}“
- Das Anlegen von Inhaltsverzeichnissen innerhalb einer Seiten mit „{{TOC}}“
- Das Anlegen von Tabellen – das ist bei jeder Syntax unterschiedlich, aber oft mit „|Zelle 1|Zelle 2|“
- Die Verwendung von Bildern und Grafiken sowohl als verlinkte Dateien (z.B. PDF) als auch direkt im Text
- Die Verlinkungen auf Dokumente, Internetseiten und andere Projekte einschließlich Textanker
Schlussbemerkung
Wenn man sich als Technikredakteur vor Augen führt, dass man in der Technikdokumentation oft für stumpfsinnige Tätigkeiten wie die Formatierung oder die Nachverfolgung von Informationsprozessen („Wann wurde diese Tabelle aktualisiert?“) häufig Zeit opfert, die auf Kosten der Qualität des Inhalts gehen, spricht kaum noch etwas gegen die Nutzung eines Wikis für die Erstellung.
Man muss nur das Papier loslassen…3
Wer das unverbindlich ausprobieren will ohne gleich die halbe IT-Abteilung in den Wahnsinn zu treiben (oder die Projektleitung auf den Geschmack zu bringen): Es gibt fertige Pakete, die sich lokal oder in der Cloud testen lassen, beispielsweise von Bitnami.
Lachen Sie nicht, aber es gibt Kunden, die ihre Dokumentation mit PowerPoint erstellt haben möchten – einschließlich Inhaltsverzeichnis… ↩
Damit soll nicht nur die Information geschützt werden, sondern vor allem auch das (ehemalige) Mitglied vor Informationen, die es nicht mehr benötigt. ↩
Ja ich weiß, jetzt schreit der Nächste „Maschinenrichtlinie!“, aber erstens steht nirgendwo, dass Papier überall erforderlich ist, noch kann man mit Wikis allen Anforderungen an eine Endnutzerdokumentation gerecht werden. Das ist allerdings bei vielen Dokumenten erstens gar nicht erforderlich – und zweitens erfüllen dies auch viele papierzentrierte Dokumentationen nicht. ↩