Technisches Schreiben

Dokumentation aus dem Produkt geschrieben, nicht aus der Spezifikation

Die meisten schlechten Dokumentationen wurden aus einem Anforderungsdokument oder aus dem Gedächtnis eines Entwicklers geschrieben. Sie beschreibt, wie das Feature gedacht war, nicht den Bildschirm, den der Nutzer tatsächlich sieht, mit seinem umbenannten Button und dem zusätzlichen Bestätigungsschritt. Der Nutzer folgt Schritt vier, findet nichts Passendes und eröffnet ein Ticket.

Wir führen jeden Arbeitsschritt im Produkt aus, bevor wir ihn beschreiben – in einem Testkonto und in der Rolle, die der Leser später hat. Wo ein Schritt anders reagiert als vom Team erwartet, halten wir es fest, denn Dokumentationsarbeit bringt regelmäßig Fehler ans Licht, die niemand gemeldet hatte. Diese Liste erweist sich oft als genauso wertvoll wie die Dokumentation.

Die Aufgabe von der Erklärung trennen

Ein Nutzer, der eine Rechnung exportieren will, möchte nicht zuerst drei Absätze zum Abrechnungsmodell. Ein Nutzer, der das Abrechnungsmodell verstehen will, möchte keine nummerierte Liste von Klicks. Beides in einem Artikel zu vermischen, macht beides schwerer zu finden und langsamer zu lesen.

Wir teilen Inhalte in Aufgaben (wie man eine Sache macht), Konzepte (wie etwas funktioniert und warum) und Referenz (Einstellungen, Felder, Limits, Fehlercodes). Jeder Typ hat seine eigene Vorlage, damit die Seiten konsistent bleiben, nachdem wir übergeben haben und Ihr Team den vierzigsten Artikel ergänzt.

Die Terminologieliste hält das Ganze über die Zeit kohärent. Wenn die Oberfläche 'Arbeitsbereich' sagt, nennt die Dokumentation dieselbe Sache nie 'Projekt' oder 'Konto'. Es ist ein kleines Dokument, das den Großteil der von Nutzern gemeldeten Verwirrung verhindert.

• Aufgabenartikel: ein Ziel, nummerierte Schritte, das Ergebnis, das der Nutzer sehen soll
• Konzeptartikel: das Modell hinter einem Feature, mit Diagramm, wo es hilft
• Referenzseiten: jedes Feld, jede Einstellung und jedes Limit in einer übersichtlichen Tabelle
• Fehlerbehebung: die Fehlermeldung im Wortlaut, ihre Ursache und die Lösung