Mit René Pfeiffer zum Schreiben von technischen Dokumentationen, den Unterschieden zum kreativen Schreiben, den ganz eigenen Herausforderungen an technische Schreiber und was alles schiefgehen kann, wenn man das nicht ordentlich macht.

Musik am Beginn: Adam Selzer, „Vintage News“

***

Sascha Lobos Debatten-Podcast: Upload-Filter und Urheberrecht: Deutschland, das Land des Digital-Trumpismus

Talk von pascoda bei der GPN18 zu den größten IT-Fails

luchs.at

Für englische Texte, die nicht von Natives geschrieben werden:

Guter Sekundär-/Tertiärquelleneinstieg:

Auch technische Dokumentation kann spannend sein!

Technische Prozesse & Software müssen dokumentiert werden. Oft machen das die Techniker*innen „hinterher noch schnell“, mit all dem Wissen, das sie ohnehin haben.

Wenn man einfach anfängt, eine Doku zu schreiben, ist schon etwas schief gegangen. Zuerst braucht man einen Plan und einen Ablauf.

Auch Beispiele sind sehr hilfreich und machen oft den Großteil der Arbeit und Zeit beim Schreiben aus.

Bilder helfen auch.

In einer technischen Dokumentation sind Tätigkeiten beschrieben. Oft werden Schritte beschrieben und dann kommt im nächsten Schritt eine Information dazu, bei der es gut gewesen wäre, sie gleich von Beginn an zu haben.

Guter Tipp: Wie bei Strickmustern oder Rezepten immer einmal vorher komplett durchlesen!

Das sollte nach Möglichkeit aber nicht der Fall sein. Wenn eine Doku gut geschrieben ist, kann man sie Schritt für Schritt durchmachen, ohne sie zweimal zu lesen.

Auch Beispiele sollten passend ausgesucht sein. Es hilft nichts, wenn ein super komplexes Beispiel abgehandelt wird, aber der Leser den Einstieg nicht schafft.

Es ist immer gut, wenn man weiß, wo man ist. Auf Schreiber*innen-Seite ist also zu bedenken, wo sich der Leser*innen gerade befinden könnte. Analog zur Übersichtskarte mit dem roten Punkt „Sie sind hier“.

Es ist auch immer gut, wenn man die Software oder das Gerät wirklich kennt, über das man gerade schreibt. Selbst wenn man es selbst nicht gebaut hat, kann – und sollte – man sich mit denjenigen unterhalten, die es gebaut haben, um zu erfahren, was es denn tut, wie es funktioniert. Wichtige Fragen dabei sind, was man damit alles machen kann, wie man es in Betrieb nimmt / installiert, etc., was sind die Prozeduren/Prozesse, die das Ding machen soll, …

Das Wichtigste an einer technischen Dokumentation ist das Inhaltsverzeichnis. Danach, gleich am Anfang, sollten nicht gleich die komplexen Beispiele kommen. Am Anfang sollte man davon ausgehen, dass noch nichts da ist und die technische Doku soll die Anwender*innen dahin bringen, was sie eben machen wollen.

Eine Dokumentation ist dann gut, wenn sie den Bereich „FAQ – frequently asked questions“ nicht braucht. Denn es sollte keine Fragen geben, wenn die Doku ordentlich geschrieben ist.

Was in Dokus oft fehlt, sind die Dinge, die schiefgehen können – die Take-Out, quasi.

Das Raketen- & Astronautenbeispiel war die Apollo8 – auch genannt im Talk von pascoda bei der GPN18 (ab Minute 17:22).

Wenn man ausgeschlafen ist, Kaffee hatte und alles super läuft, passiert selten was. Aber auch ausgebildete Menschen machen in Stress-Situationen Fehler. Deswegen gibt es in Flugzeugen Checklisten. Natürlich wissen Pilot*innen und Crew, was zu tun ist. Aber wenn Stress ist, kann so eine Checkliste sehr zur Beruhigung beitragen. Ebenso in der Notaufnahme. Checklisten wiederholen zwar viel, aber das schadet nicht.

Solche Listen, eine Troubleshooting-Abteilung und Fehlerbeschreibungen sollten in jeder Doku vorhanden sein.

Ebenso sollten Checklisten für die Anwender*innen vorhanden sein, um auftretende Fehler rekonstruieren zu können. Z.B. Welches Betriebssystem, welcher Browser in welcher Version, etc., um es den Menschen, die einem dann helfen wollen, einfacher zu machen, den Fehler nachzustellen.

Es gab auch mal so etwas Altmodisches wie Reparaturscheine.

Oft gehen Programmierer davon aus, dass die Anwender*innen wissen, welche Informationen benötigt werden. Die Erfahrung zeigt, dem ist nicht so.

Auch wenn Dinge klar sind, trotzdem lieber hinschreiben!

Man sollte auch Abbildungen und Diagramme als Stilmittel schätzen. Gerade für Abläufe sind.

Bankomaten sind oft schwer zu bedienen, weil sie eine Mischung aus Tastenfeld und Touchscreen haben und oft nicht klar ist, was zu machen ist oder welches Eingabewerkzeug jetzt funktioniert.

Ganz wichtig sind auch Begriffserklärungen. Beim kreativen Schreiben sind Wortwiederholungen ein No-Go. Beim technischen Schreiben ist das dagegen aber durchaus erwünscht! Wenn man nämlich für ein und dieselbe Sache 4 verschiedene Wörter verwendet, kann das zu Verwirrung führen; sowohl bei Lernenden als auch bei etwas erfahreneren Nutzer*innen.

Das liest sich vielleicht schlimm, aber wenn man ein Wort dauernd liest, merkt man es sich dafür auch schneller.

Technische Dokumentationen eignen sich nicht sehr zum Reimen.

Probleme können in unserer heute bereits sehr vernetzten Welt ein größeres Ausmaß annehmen als „ich versuche das nach dem Mittagessen nochmal“. Es ist mittlerweile nicht mehr unüblich, dass ein Problem ganze Infrastrukturen lahmlegt.

Was wir im letzten Jahr mit #wannacry gesehen haben war, wie kritische Infrastruktur durch eine sich selbst weiter verbreitende Welle an Erpressungstrojanern Teile von Krankenhäusern lahmgelegt hat. Für die Menschen in den jeweiligen IT-Abteilungen war das eine extreme Krisensituation. Da steht dann auf der Checkliste ganz oben: „Durchatmen.“

Die Informationsbeschaffung läuft normalerweise in Ruhe ab und im Krisenfall kommt man häufig in Bereiche, wo man konkret nichts tun kann.

Zurück zur Doku heißt das, dass man auch den Fall abbildet, dass die Anwender*innen nichts tun können und Hilfe brauchen und was in so einem Fall zu tun ist.

Das Verhalten von Software und Menschen in Krisensituationen geht allerdings über die Möglichkeiten einer technischen Doku hinaus. Aber man muss die Fälle schon adressieren und nicht so tun, als gäbe es das alles gar nicht.

Auch der Fall eines unerwünschten Datenverlusts sollte abgedeckt sein. Zum Beispiel, wenn in einem System eine Festplatte kaputt ist und eine nicht, dann will man die richtige austauschen und eine Doku sollte dabei helfen und es nicht noch schlimmer machen.

Daten löschen kann jederzeit passieren! Nicht nur Autore*innen.

Backups! Backups! Backups!

Ein Backup hilft auch, wenn man z.B. eine Software auf eine neuere Version updaten möchte. Das Schlimmste, was passieren kann, wenn etwas schiefläuft ist, dass sich nichts ändert. Das entspannt ungemein.

Die technische Autorin hat auch eine Aufgabe als „Therapeut“, schlechte Nachrichten schonend beizubringen.

Technische Dokumentation schreiben ist deswegen so aufwändig, weil man alles noch einmal durchspielen muss.

Es kann sein, dass Informationen in Dokus falsch sind oder nicht (oder schlecht) getestet.

Vor allem sind oft ganz viele Informationen nur implizit in Dokus drin. Wenn man schreibt „mach ein Backup, ehe Du anfängst“, kann das durchaus bedeuten, dass dieses Backup zwei Tage braucht – das ist bei Mailservern, etc. durchaus üblich. Das sollte man aber auch erwähnen, dass Vorbereitungen einen bestimmten Zeitrahmen in Anspruch nehmen können, damit die Anwender*innen das gleich einplanen und nicht währenddessen drauf kommen.

Deswegen steckt üblicherweise viel Hirnschmalz und Zeit in einer technsichen Dokumentation. Die Aufbereitung und Strukturierung nimmt viel Zeit in Anspruch. Und ja, man kann auch Storyboards für Fakten machen! Man kann auch allen Komponenten Charakternamen geben und eine Story bauen. Im Falle von Servern ist das sogar eine ganz gute Idee. Falls es wirklich einen Malwareangriff gibt oder eine Hackerin sich in die Infrastruktur reingehackt hat, ist es schon gut, „Mailserver2“ nicht auf dem Silbertablett zu servieren. Server „Gandalf“ hat durchaus einen Sicherheitsaspekt.. Vor allem sollten alle Komponenten klar und unmissverständlich benannt sein.

Loki und Sokrates hätten sich möglicherweise gut verstanden.

Ich bin vor einer Weile auf Laptops umgestiegen, da ich gern in Kaffeehäusern schreibe. Da ist es unpraktisch, den Standrechner mitzunehmen. Obgleich das Anfang der 90er für Klausuren im IT Bereich wohl möglich war. Für LAN Parties hat man ja auch ganze Rechner mitgeschleppt.

IT klingt ja immer so trocken und unkreativ. Man muss aber trotzdem kreativ sein, um an alles zu denken, was passieren kann. Denn alles was passieren kann, wird auch passieren. Selbst wenn es einen simplen Entscheidungsbaum gibt, man kann dies, das oder jenes mit dem Ding machen, sollte man darüber nachdenken, was man denn wirklich noch alles damit machen könnte. Es passiert oft, dass Dinge für etwas verwendet werden, wofür sie nicht gedacht waren. Das ist ja der Wortsinn von „Hacken“: Dinge anders verwenden, als sie vom Hersteller gedacht waren. Das plakative Beispiel ist da der Bierdeckel unter dem wackelnden Tischbein.

Weiter mit Kreativität: Kleine Dinge können sehr große Auswirkungen haben. Das Netz kennt keine lokalen Grenzen. Speziell, wenn man vernetzte Software hat, da weiß man ja nicht, mit wem die jetzt redet. Wer kann sie verwenden?

Wenn man irgendwo in einer technischen Doku den Satz findet: „Diese Applikation ist nur in internen Netzwerken zu verwenden“, dann kann man davon ausgehen, dass irgendwas fehlt. Irgendetwas wurde bei der Programmierung nicht betrachtet und viele Annahmen gemacht. Natürlich ist der Satz an sich legitim, aber man sollte daraus einen kleinen Absatz in der Doku machen und erklären, warum das so ist.

Niemand wird sich darüber beschweren, wenn der Mietwagen nicht gepanzert ist. Natürlich ist er das nicht und niemand regt sich darüber auf. Aber man muss auch bei Software oder Hardware so ehrlich sein und dazuschreiben: „Diese Software/Hardware ist nicht für Hochsicherheitsnetze gedacht und nicht für öffentliche Verwendung.“ Eine Dokumentation muss ehrlich bleiben. Das ist kein Marketingfolder, sondern technische Dokumentation.

Es gab im letzten Jahr den Fall, wo in einer Firma eine vernetzte Kaffeemaschine eingebaut wurde, die die Techniker aber nicht in das vorgesehene Sub-Netz bekommen haben. Stattdessen haben sie die Maschine dann in das Netzwerk gehängt, wo auch die ganzen Rechner der Angestellten drin hingen. Über die Kaffeemaschine kam dann eine Malware in das Firmennetzwerk und dann war mal die gesamte Firma down, weil die Kaffeemaschine mit den Zugangsdaten „admin/admin“ oder so eben ein Einfallstor aufgemacht hat. Da hätte wohl auch besser stehen sollen: „Bloß nicht in firmeninterne Netzwerke hängen!“

Das ist momentan leider ein großes Missverständnis auf Konsumentenebene. Das ganze netzwerkfähige Zeug (#IoT), das Weihnachten aus der Verpackung genommen und einfach mal ins Netz gehängt wird, ohne Standardpasswörter wie admin/admin oder 0000 zu wechseln mit dem Gedanken: Das machen wir dann mal später, jetzt geht das ja mal eben so. Und jetzt kommt das große Missverständnis: Der Gedanke: „Das wird ja niemanden interessieren, ich bin ja zu uninteressant für ‚die‘. Aber: Da sitzt niemand, der darauf wartet, dass Hansi Müller genau diese Kamera ins Netzwerk hängt, um sich dieses eine Ding zu schnapüpen und sich die Videos aus seinem Vorgarten anzugucken. Stattdessen wird das Gerät automatisch von zum Beispiel einem Botnetzwerk gefunden und ebenfalls zu einem „Bot“ gemacht. Es wird zu einem Sprungbrett für andere.

Renés Wunsch: Wenn man etwas auspackt, muss oben auf die technsiche Doku liegen und erst wenn man die gelesen und verstanden hat, bekommt man das Ding selber! ;D

Das ist eine besondere Kategorie für Autor*innen von technischen Dokumentationen, die man beschreiben kann. Wenn man noch nicht vernetzte Geräte nimmt wie beispielsweise eine Gastherme, da gibt es auch Dinge, die man nicht sieht, die aber gefährlich sind; Kohlenmonoxyd etwa. Manche Geräte haben dafür einen Sensor, manche nicht, aber das steht als Gefahrenquelle sicher in der Dokumentation zu dem Gerät drin.

Auch Dinge, die man nicht sieht – ob das Kohlenmonoxyd ist oder Netzwerktraffic – die muss man einfach beschreiben. Wenn es Risiken gibt, müssen die beschrieben werden.

Einige Hersteller haben es schon verstanden. Es gibt mittlerweile Dinge, die man nicht mehr in Betrieb nehmen kann, ohne das Passwort zu ändern. So soll das auch sein.

Für die Doku heißt das wieder: Man muss ehrlich sein. Da stößt man an die Grenzen der Vermarktung. Es gibt die Fälle, wo den Autor*innen von Dokus gesagt wird „das lassen wir jetz weg“. Das gibt es leider wirklich.

Telemetrie ist ein Begriff, den man aus der Formel1 kennt. Telemetriedaten sind Betriebsdaten von Fahrzeugen oder Geräten zu Laufzeiten abführt. In der Formel1 wissen die Mechaniker am Rand, wie es dem Auto geht. Und Microsoft weiß, wie es dem Windows geht. Windows10 meldet periodisch $Dinge und am anderen Ende der Leitung weiß jemand was. Und das ist auch leider der Dokumentationsstand, den wir für den Betrieb haben. Was sie genau übertragen ist in der Dokumentation nicht aufgeschlüsselt.

Wenn etwas nicht dokumentiert ist, hat das üblicherweise bestimmte Gründe.

Die TU Wien führt gerade Ethik im ersten Studienabschnitt verpflichtend ein – das ist super! Ethik für technische Autoren wäre auch etwas. Bei einer Kettensäge beschreibt man ja auch die Gefahren. Man schreibt ja nicht: „Pass halt auf, wird schon nix sein.“ Auf der Datenebene macht man das aber. Es ist unverständlich, warum das nicht gleichwertig ist.

Dass die TU Wien jetzt Ethik verpflichtend einführt ist ein Schritt in die richtige Richtung, um Menschen dazu zu bringen, darüber nachzudenken, was mit ihrer Software alles gemacht werden kann. Wir reden hier nicht nur von Schreibprogrammen oder lustigen Spielen mit Pinguinen, sondern von Systemen, die in Krankenhäusern im Einsatz sind oder an Flughäfen in der Flugsteuerung. Das sind alles Sachen, die von Menschen programmiert und dokumentiert werden. Deswegen ist es so wichtig, dass die Sachen ordentlich geschrieben/programmiert werden.

„Doku or it didn’t happen!“

Schaden tut es nicht, diesen Anspruch an Vollständigkeit und Sorgfalt zu übernehmen. Wenn man das nämlich nicht tut, kann das in der Anwendung gegebenenfalls scheußlich schiefgehen. Wenn ein Flugüberwachungssystem schlecht dokumentiert ist, das will keiner haben!

Es gibt noch immer Systeme, man wundert sich, wo … Die laufen einfach länger, als sie gedacht waren. Das kann etwas Kleines sein wie ein privates Content Management System, das 2000 geschrieben wurde und noch immer funktioniert. Das kann aber auch ein kommerzielles System sein, das vor zig Jahren mal gebaut und zusammengeschraubt wrude und plötzlich ist das nach 20 Jahren immernoch in Betrieb.

Wenn man eine technische Dokumentation schreibt, muss man davon ausgehen, dass das Ding auf unbestimmte Zeit läuft.

Ein Kriegsschiff – ein voll mit Waffen ausgestattetes Stück Stahl gondelt da irgendwo auf dem Meer rum und ist aufgrund seines Betriebssystems komplett unsicher. Wenn man das jemals an ein Netzwerk hängt, kann es am Ende noch sein, dass auch die Kanonen noch Teil eines Botnetzes werden.

Ein Quell ewiger Freude für Krimiautor*innen!

Und dann gibt es Firmen, die sich darauf spezialisiert haben, dass sie uralte Hardware, teilweise aus den Siebzigern, reparieren und durchgebrannte Teile ersetzen für fünfstellige Beträge, damit das System, das da seit den Siebzigern läuft, weiter betrieben werden kann. Oft sind die, die das System für genau diesen Zweck gebaut hat, leider schon vor X Jahren verstorben ist und niemand mehr in der Lage ist, dieses Ding zu warten. Oft gibt es auch den Source Code nicht mehr – also das, wie es mal geschrieben wurde – sondern nur noch die kompilierte Version.

Zur Erklärung: Es läuft auf den Geräten nicht der Quellcode, sondern immer eine kompilierte, eine zusammengestellte Version, die eine lauffähige Umgebung schafft. Der Quellcode ist bei vielen Dingen, insbesondere kommerziellen Produkten nicht einsehbar. Es gibt auf der anderen Seite Open Source Foftware, also offener Quellcode, den man reingucken kann, was das tatsächlich tut.

Tipp für SciFi Autor*innen: Es gibt auch heute noch diese riesigen Mainframe Computer, die ganze Hallen füllen. Die haben eine lange Laufzeit, weil sie einfach teuer sind, die tauscht man frühestens alle zehn Jahre. Man muss da in Dekaden rechnen! In den Sechzigern hat man damit angefangen und dann pro Dekade eine neue Generation. Wenn man den Computer nun austauscht, dann bringt die neue Generation eine Umgebung mit, in der man die alten Programme einfach 1:1 weiterlaufen lassen kann, ohne sie zu modifizieren. In der Firma selber scheiden aber immer mal Mitarbeiter aus und da wurde mal ein Programm geschrieben, das läuft gut und dann ist irgendwann mal die Doku verschwunden oder auch einfach nie geschrieben worden, … Also selbst moderne Mainframes haben oft Code laufen, der älter ist als sie selbst, der nicht mehr gewartet wird, nicht dokumentiert ist, aber läuft, weil man weiß ja nie [was passiert, wenn man das abstellt].

Deswegen sollte man sich beim Schreiben Mühe geben, dass man das auch in 30 Jahren noch lesen möchte und kann.

Unterstützt den Vienna Writer’s Blog & Podcast