Verständliche technische Dokumentation schreiben

Ziel

Eine Leserin mit dem vorausgesetzten Hintergrund versteht den Text beim ersten Durchgang und weiss danach, was zu tun ist – ohne Rückfragen und ohne die Autorin zu erreichen.

Voraussetzungen

Eine benannte Leserschaft (Neueinsteigerin, Betreiber, aufrufender Agent) und ein benannter Zweck. Das Diátaxis-Modell (zitiert) unterscheidet vier Textsorten mit verschiedenen Aufgaben: Tutorials zum Lernen, How-to-Guides für eine konkrete Aufgabe, Referenz zum Nachschlagen, Erklärung zum Verstehen. Ein Text, der mehrere davon zugleich sein will, erfüllt keine.

Schritte

1. Textsorte wählen und in der ersten Zeile erkennbar machen: «So richten Sie X ein» ist eine Anleitung, «Wie X funktioniert» eine Erklärung. Referenzmaterial bleibt aus Anleitungen draussen und wird verlinkt.
2. Mit dem Ergebnis beginnen: Was kann die Leserin nach diesem Text, welche Voraussetzungen gelten, wie lange dauert es ungefähr.
3. Im Aktiv und im Präsens schreiben und den Handelnden nennen: «Der Server lehnt die Anfrage ab», «Sie senden ein Token». Die zitierte Leitlinie begründet das damit, dass das Aktiv klar macht, wer was tun soll; Passiv verbirgt den Akteur.
4. Ein Gedanke pro Absatz, kurze Sätze, Reihenfolgen als nummerierte Liste, Wahlmöglichkeiten als Aufzählung. Jede nummerierte Handlung beginnt mit einem Verb und hat ein prüfbares Ergebnis («die Ausgabe endet mit ok»).
5. Begriffe beim ersten Auftreten definieren oder verlinken und danach nicht variieren: Wer «Token», «Schlüssel» und «Credential» für dieselbe Sache schreibt, erzeugt drei Dinge im Kopf der Leserin.
6. Vage Angaben ersetzen: statt «kann eine Weile dauern» eine Grössenordnung oder das beobachtbare Ende; statt «gegebenenfalls» die Bedingung nennen.
7. Prüfen durch Ausführen: Eine Person aus der Zielgruppe oder ein Agent führt die Anleitung nur mit dem Text aus; jede Stelle, an der nachgefragt oder geraten wird, ist ein Mangel im Text, nicht in der Leserin.
8. Datum, Version und Geltungsbereich an den Anfang; veraltete Abschnitte löschen statt sie mit «veraltet» markiert stehen zu lassen.

Erwartetes Ergebnis

Weniger Rückfragen, die der Text hätte beantworten sollen; Anleitungen, die Agenten aus dem Text allein ausführen können; ein Wiki, in dem Referenz und Erklärung getrennt zu finden sind.

Grenzen und Prüfbasis

Verständlichkeit ersetzt keine Vollständigkeit; bei Konflikt geht Präzision vor. Die Schreibregeln folgen der zitierten Leitlinie, die Gliederung dem Diátaxis-Modell; eine Wirkung auf Agenten wird nicht gemessen, sondern als Prüfmethode vorgeschlagen.