Wie Sie technische Dokumentation schreiben

Wählen Sie eine Aufgabe, einen Leser und eine einzige verlässliche Quelle. Schreiben Sie dann die Schritte in einfacher Sprache, testen Sie sie mit jemandem, der sie nicht geschrieben hat, und streichen Sie alles, was dem Leser nicht hilft, die Aufgabe zu Ende zu bringen.

Vor dem Schreiben

Gute technische Dokumentation beginnt vor dem ersten Satz. Wählen Sie zuerst eine Aufgabe. Schreiben Sie zum Beispiel über „ein neues Payment-Gateway verbinden“, nicht über „die App dokumentieren“. So haben Sie ein klares Ziel und die Seite bleibt nützlich.

Als Nächstes benennen Sie den Leser. Ein Entwickler braucht Hinweise zur Einrichtung, Befehle und Sonderfälle. Ein Support-Mitarbeiter braucht Symptome, Prüfungen und Lösungen. Eine Projektleitung braucht Status, Abhängigkeiten und Übergaben. Eine Seite kann eine dieser Gruppen gut unterstützen, oder bei allen drei scheitern.

Sammeln Sie dann die verlässliche Quelle. Das kann Code, Tickets, Screenshots, Design-Notizen, Protokolle, ein Runbook oder eine alte Anleitung sein, die noch einen guten Abschnitt enthält. Wenn sich zwei Quellen widersprechen, halten Sie an und klären Sie, welche gewinnt, bevor Sie den Entwurf schreiben.

Wählen Sie das Format, bevor Sie mit dem Schreiben beginnen. Eine Einrichtungsanleitung, eine Referenzseite und eine Fehlerbehebungsseite brauchen jeweils eine andere Form. Bei einem Controller für einen Stehschreibtisch kann eine Einrichtungsanleitung das Koppeln und Kalibrieren erklären. Eine Referenzseite kann Tastenbezeichnungen und die Bedeutung der Lichter auflisten. Eine Fehlerbehebungsseite kann einen klemmenden Hub oder eine blinkende Fehlermeldung behandeln.

Wie Sie technische Dokumentation schreiben

• Schreiben Sie zuerst das Ergebnis. Sagen Sie, was der Leser am Ende kann. Beispiel: „Am Ende ist die Staging-App mit Stripe verbunden.“
• Nutzen Sie einen einfachen Ablauf: Zweck, was Sie brauchen, Schritte, Ergebnis, Lösungen. So bleibt der Leser dran.
• Schreiben Sie nur eine Handlung pro Schritt. „Öffnen Sie die Admin-Konsole. Wählen Sie Billing. Wählen Sie Zahlungsmethode hinzufügen.“ Das ist leichter zu folgen als ein langer Absatz mit fünf Verben.
• Verwenden Sie exakte Namen für Schaltflächen, Felder, Ordner, Befehle, Fehlercodes und Dateinamen. Wenn auf dem Bildschirm Zahlungsmethode hinzufügen steht, nennen Sie es in der Dokumentation nicht Neue Karte.
• Bleiben Sie bei den Begriffen einheitlich. Wenn Sie in Schritt 1 Workspace schreiben, wechseln Sie in Schritt 4 nicht zu Projektbereich.
• Setzen Sie das wahrscheinliche Problem direkt neben den Schritt, der es auslösen kann. Wenn der Zugriff oft das Problem ist, schreiben Sie das dort dazu. Beispiel: „Wenn die Schaltfläche fehlt, prüfen Sie, ob Sie Billing-Admin-Zugriff haben.“
• Nutzen Sie kopierbare Beispiele für Software und Code. Zeigen Sie zuerst den Befehl, dann direkt danach das erwartete Ergebnis. So kann der Leser seinen eigenen Bildschirm schnell prüfen.
• Schreiben Sie kurze Absätze. Ein Gedanke pro Absatz reicht. Wenn ein Absatz zu viele Gedanken enthält, teilen Sie ihn in zwei auf.
• Streichen Sie alles, was jemandem nicht hilft, die Aufgabe zu Ende zu bringen. Hintergrund ist nur dann nützlich, wenn er einen Fehler verhindert.
• Fügen Sie den nächsten Schritt am Ende hinzu. Verlinken Sie zum Beispiel die Testseite, die Fehlerbehebungsseite oder den nächsten Einrichtungsabschnitt.

Ein einfaches Schritt-Muster

Ein gleichmäßiges Schritt-Format hält die Dokumentation lesbar, wenn die Aufgabe kompliziert wird. Nutzen Sie diese Form für jeden Schritt: Handlung, Ergebnis, falls nötig Lösung. Das funktioniert für Software-Einrichtung, Projektübergaben und befehlsbasierte Abläufe.

Beispiel für eine Entwicklerseite: „Führen Sie npm install aus. Sie sollten sehen, wie sich die Paketliste aktualisiert. Wenn es fehlschlägt, prüfen Sie, ob Node 20 installiert ist.“ Das gibt dem Leser etwas zum Tun, etwas zum Erwarten und etwas zum Prüfen.

Vorher: „Dann kümmern Sie sich um das Abhängigkeitsproblem.“ Nachher: „Führen Sie npm install aus. Wenn ein Berechtigungsfehler angezeigt wird, öffnen Sie das Terminal erneut als Benutzer mit Schreibzugriff.“ Die zweite Version ist langsamer zu schreiben und schneller zu nutzen.

Für eine Seite zum Tisch-Controller könnten Sie schreiben: „Halten Sie die Auf- und Ab-Tasten drei Sekunden lang gedrückt. Das Display sollte einmal blinken. Wenn nicht, ziehen Sie den Controller vom Strom und versuchen Sie es erneut.“ Das ist klar, prüfbar und konkret.

Was gute technische Dokumentation enthält

Eine nützliche Seite folgt meist dieser Reihenfolge: Titel, kurze Einleitung, Voraussetzungen, Schritte, erwartete Ergebnisse, Lösungen, nächster Schritt. Diese Reihenfolge funktioniert, weil sie die Fragen des Lesers in derselben Reihenfolge beantwortet, in der sie auftauchen.

Der Titel sollte die Aufgabe benennen. Die Einleitung sollte dem Leser sagen, für wen die Seite gedacht ist und was sie abdeckt. Die Voraussetzungen sollten nur das nennen, was den Fortschritt blockiert, etwa ein Konto, ein Kabel, eine Version oder ein Login.

Die Schritte sollten in der echten Reihenfolge stehen, nicht in der, die clever klingt. Setzen Sie Warnhinweise nur dort ein, wo sie wichtig sind. Fügen Sie einen kurzen Abschnitt zu den häufigsten Fehlern hinzu. Beenden Sie mit einem klaren Endpunkt, zum Beispiel einem Testlauf oder einer Übergabe.

Für eine Seite zur Einrichtung eines Payment-Gateways könnte das so aussehen: „Verbinden Sie Stripe mit der Staging-App. Sie brauchen Admin-Zugriff und einen Testschlüssel. Folgen Sie den Schritten, um den Schlüssel einzufügen, die Einstellung zu speichern und eine Testabbuchung auszuführen. Wenn der Test fehlschlägt, prüfen Sie den Schlüssel und die Kontoberechtigungen. Gehen Sie dann zur Seite für die Webhook-Einrichtung.“

Vor dem Veröffentlichen testen

Verlassen Sie sich nicht auf den Entwurf, nur weil er sich für Sie gut liest. Geben Sie ihn an jemand anderen weiter, der ihn nicht geschrieben hat. Bitten Sie diese Person, ihm ohne Hilfe zu folgen. Beobachten Sie, wo sie innehält, rät oder zurückspringt.

Wenn die Person innehält, fehlt der Seite vielleicht eine Voraussetzung oder ein kleiner Einrichtungs-Schritt. Fügen Sie diesen Schritt an der ersten Stelle hinzu, an der er gebraucht wird.

Wenn die Person rät, ist die Formulierung unklar. Ersetzen Sie „den richtigen Wert eingeben“ durch den genauen Feldnamen, die genaue Bezeichnung oder den genauen Dateipfad.

Wenn die Person zurückspringt, stimmt die Reihenfolge nicht. Verschieben Sie den Schritt weiter nach vorn oder teilen Sie die Seite auf, damit der Leser nicht hin- und herspringen muss.

Versuchen Sie, den unklaren Teil zu beheben, nicht nur den Satz darum herum. Manchmal ist die eigentliche Lösung eine neue Voraussetzung, ein anderer Screenshot oder eine zweite Seite.

Für eine schnelle Prüfung gehen Sie tools manual check durch. Wenn Sie dieselbe Gewohnheit für physische Anleitungen brauchen, vergleichen Sie die Struktur mit this guide.

Was meist schiefläuft

Das häufigste Problem ist zu viel Kontext und zu wenig Handlung. Leser brauchen keine lange Vorgeschichte, bevor der Schaltflächenname kommt.

Ein weiterer Fehler ist, mehrere Aufgaben auf einer Seite zu mischen. Einrichtung, Fehlerbehebung und Referenz konkurrieren dann um Platz. Trennen Sie sie, wenn der Leser den Denkmodus wechseln muss.

Screenshots veralten schnell. Nutzen Sie sie nur für Bildschirme, die sich selten ändern. Wenn sich Beschriftungen oft verschieben, verwenden Sie lieber einen kurzen Hinweis oder ein zugeschnittenes Bild statt eines vollständigen Screenshots.

Unklare Wörter sorgen ebenfalls für Probleme. Verzichten Sie auf „einfach“, „leicht“ und „nur“. Sie beheben weder eine festhängende Bereitstellung noch eine fehlende Berechtigung.

Wenn eine Seite zu aufgebläht wirkt, streichen Sie zuerst das Überflüssige. Lassen Sie die Schritte stehen, die den Leser zu einem funktionierenden Ergebnis führen.

Wie lange es dauert

Eine kurze Anleitungsseite kann 30 bis 60 Minuten dauern, wenn die Quelle sauber ist und die Aufgabe einfach ist.

Ein normaler Leitfaden zur Software-Einrichtung dauert meist 2 bis 4 Stunden, wenn Sie Entwurf, Prüfung der Schritte und Bearbeitung mit einrechnen.

Eine größere Projektseite mit Sonderfällen, Screenshots und Prüfrunden kann fast einen ganzen Tag dauern.

Der langsame Teil ist meist der Nachweis, dass die Schritte funktionieren, nicht das Schreiben selbst. Wenn der Ablauf unübersichtlich ist, schreiben Sie die Dokumentation, während Sie die Aufgabe erledigen. So fallen fehlende Klicks, versteckte Annahmen und holprige Formulierungen schnell auf.

Wann eine Video-Version hilft

Eine geschriebene Seite ist weiterhin der beste Ort für Suche, Nachschlagen und exakt kopierbaren Text. Ein Video hilft, wenn die Aufgabe viele Schritte hat, sich Bildschirme ändern oder Support-Fragen sich wiederholen. Das ist bei Onboarding, Einrichtung und praktischen Abläufen oft der Fall.

Wenn Sie bereits eine Anleitung oder eine Anleitungsseite haben, kann eine kurze Video-Version daneben stehen. Manual to Video wandelt eine vorhandene Anleitung in ein animiertes, mit Untertiteln versehenes Schritt-für-Schritt-Film in Ihren Markenfarben und mit Ihrem Logo um. Es funktioniert auch mit einem QR-Code auf der Anleitung, dem Karton, einer Produktseite oder einem Support-Artikel.