Hilfeartikel schreiben, die Kunden wirklich nutzen
Jemand gibt „Rechnungen exportieren“ in die Suche Ihres Help-Centers ein. Er bekommt drei Treffer: „Abrechnung im Überblick“, „Berichte“ und „Erste Schritte mit Daten“. Keiner davon enthält das Wort Export. Er schließt den Tab und schreibt Ihnen eine E-Mail.
Das ist das Problem der meisten Hilfeartikel. Sie sind danach geordnet, wie das Produkt gebaut ist, nicht danach, was Menschen erreichen wollen.
Hier also die kurze Antwort. Damit Ihre Hilfeartikel wirklich genutzt werden, benennen Sie jeden nach genau einer Aufgabe in den Worten des Kunden, sagen in einer Zeile, was er bewirkt, nennen alles, was vorher nötig ist, geben nummerierte Schritte mit jeweils einer Handlung, fügen einen Screenshot dort ein, wo Menschen sich meist verlaufen, und schließen mit dem, was sie sehen sollten, wenn es geklappt hat. Ein Artikel, eine Aufgabe. Wenn Sie merken, dass Sie „Sie können auch“ schreiben, ist das wahrscheinlich ein zweiter Artikel.
Der Rest dieses Beitrags liefert die Details: eine Vorlage zum Kopieren, ein Vorher-Nachher-Beispiel, was Sie zuerst schreiben sollten und wie Sie verhindern, dass alles sechs Wochen nach dem Start veraltet.
Was macht einen guten Wissensdatenbank-Artikel aus?
Niemand liest Hilfedokumente zum Vergnügen. Menschen kommen mitten in einer Aufgabe an, ein bisschen genervt, meist über die Suche (Ihre eigene oder Google) oder über einen Link, den jemand aus Ihrem Team in eine Antwort eingefügt hat. Sie überfliegen. Sie wollen Schritt 3 finden, ausführen und wieder gehen.
Ein guter Wissensdatenbank-Artikel lässt also eine überfliegende, leicht genervte Person ihre Aufgabe abschließen, ohne etwas zweimal zu lesen. In der Praxis heißt das:
- Ein Artikel, eine Aufgabe. „Kollegen einladen“ und „Rolle eines Kollegen ändern“ sind zwei Artikel. Sie verlinken aufeinander.
- Titel sehen aus wie Suchanfragen. Menschen suchen mit Verben: „Abo kündigen“, „Passwort zurücksetzen“, „Slack verbinden“. Ihre Titel sollten genauso klingen.
- Schritte sind nummeriert und unteilbar. Ein Klick oder ein Feld pro Schritt. Enthält ein Schritt „und dann“, teilen Sie ihn.
- Genaue Beschriftungen der Oberfläche, fett. Steht auf der Schaltfläche Mitglied hinzufügen, schreiben Sie nicht „klicken Sie auf die Einladungsschaltfläche“. Der Leser gleicht Wörter auf dem Bildschirm mit Wörtern in Ihrem Artikel ab.
- Er endet mit einem Ergebnis. „Sie erscheinen in der Mitgliederliste mit dem Hinweis „Ausstehend“, bis sie annehmen.“ Dieser Satz sagt den Menschen, dass sie fertig sind, und er ist der, den die meisten Autoren weglassen.
Das Diátaxis-Framework teilt Dokumentation in Tutorials, Anleitungen, Referenz und Erklärung. Die meisten Hilfeartikel sollten Anleitungen sein. Der häufige Fehler ist, alle vier auf einer Seite zu mischen, sodass jemand, der Schritt 4 sucht, sich erst durch drei Absätze darüber kämpfen muss, warum es die Funktion überhaupt gibt.
Eine Vorlage für Hilfeartikel zum Kopieren
Mit dieser Vorlage würde ich jeden Aufgabenartikel beginnen. Sie funktioniert in Zendesk, Intercom, Help Scout, GitBook oder in einem Ordner mit Markdown-Dateien in Ihrem Repository.
# [Verb] [the thing]
<!-- e.g. "Export your invoices to CSV" -->
[One or two sentences: what this does and when you'd want it.
Mention the plan or role if it's restricted.]
**Before you start**
- You need [role or permission], e.g. Admin or Owner
- [Anything to have ready: a file, an API key, a connected account]
## Steps
1. Go to **[Page name]** in the left sidebar.
2. Click **[Exact button label]**.
3. In **[Field name]**, enter [what, with an example value].
4. Click **[Confirm button label]**.
<!-- Screenshot of the step where people get stuck.
Crop to the relevant area, highlight the target. -->
## What happens next
[What they'll see when it worked. How long it takes.
Who gets notified.]
## If it didn't work
- **[Symptom in the customer's words]**: [cause and fix]
- **[Second most common symptom]**: [cause and fix]
## Related
- [The task people usually do next]
- [The reverse task, e.g. "Remove a teammate"]
Ein paar Hinweise zur Anwendung.
Die Einleitung ist kein Verkaufsgespräch. „Unsere leistungsstarke Exportfunktion gibt Ihnen volle Kontrolle über Ihre Daten“ sagt dem Leser nichts. „Laden Sie jede Rechnung eines Zeitraums als CSV-Datei herunter, die Sie in Excel oder Google Sheets öffnen können“ sagt ihm, ob er auf der richtigen Seite ist.
„Before you start“ verhindert die meisten Tickets. Der klassische Fehler: Jemand folgt sechs Schritten und erfährt bei Schritt sieben, dass nur Admins das dürfen. Setzen Sie Berechtigungen und Tariflimits an den Anfang, nicht in einen Hinweis am Ende.
„If it didn’t work“ sollte aus echten Tickets stammen. Erfinden Sie keine Fehlerbehebung. Sehen Sie den letzten Monat Support-E-Mails durch und notieren Sie, wo Menschen tatsächlich hängen geblieben sind. Zwei oder drei Punkte reichen völlig. Wenn Sie dafür einen wiederholbaren Weg suchen: Wir haben einen eigenen Leitfaden dazu geschrieben, wie Sie Support-Tickets in Hilfeartikel verwandeln.
Vorher und nachher: einen typischen Hilfeartikel umschreiben
So sieht der Artikel aus, der in der Woche entsteht, in der eine Funktion ausgeliefert wird. Das Produkt ist erfunden, das Muster nicht.
Teamverwaltung
Unsere Funktion Teamverwaltung macht die Zusammenarbeit einfach. Im Bereich Einstellungen können Sie Ihr Team verwalten, unter anderem neue Mitglieder über den Reiter Mitglieder hinzufügen, wo Sie die Schaltfläche Mitglied hinzufügen finden, und Rollen wie Admin, Bearbeiter oder Betrachter festlegen, die steuern, worauf jede Person zugreifen kann. Eingeladene Nutzer erhalten eine E-Mail. Beachten Sie, dass nur Admins Mitglieder hinzufügen können und die Anzahl der Plätze von Ihrem Tarif abhängt.
Alles, was der Leser braucht, steht darin. Es steht nur in der falschen Reihenfolge, unter einem Titel, nach dem niemand sucht, und der Haken mit den Berechtigungen kommt im letzten Satz.
Hier die Überarbeitung:
Kollegen einladen
Fügen Sie jemanden zu Ihrem Workspace hinzu, damit er Projekte ansehen und bearbeiten kann.
Bevor Sie beginnen: Sie müssen Admin sein. Jede Person belegt einen Platz in Ihrem Tarif. Wie viele Plätze Ihnen noch bleiben, sehen Sie unter Einstellungen > Abrechnung.
- Gehen Sie zu Einstellungen > Mitglieder.
- Klicken Sie auf Mitglied hinzufügen.
- Geben Sie die E-Mail-Adresse ein.
- Wählen Sie eine Rolle: Admin, Bearbeiter oder Betrachter.
- Klicken Sie auf Einladung senden.
Was danach passiert: Die Person erhält eine Einladung per E-Mail. Bis sie annimmt, steht sie in der Mitgliederliste mit dem Hinweis Ausstehend.
Falls es nicht geklappt hat: Ist Mitglied hinzufügen ausgegraut, sind alle Plätze belegt. Entfernen Sie jemanden oder buchen Sie unter Einstellungen > Abrechnung weitere Plätze.
Dieselben Fakten, ungefähr gleich lang. Aber der Titel entspricht dem, was Menschen eintippen, der Haken steht vorn, jeder Schritt ist eine Handlung, und der Leser weiß, wann er fertig ist. Die Erklärungen zu den Rollen sind in einen eigenen kurzen Artikel gewandert („Was jede Rolle darf“), der von Schritt 4 aus verlinkt ist.
Wie lang sollte ein Hilfeartikel sein?
So lang wie die Aufgabe und nicht länger. Als Faustregel landet eine Anleitung für eine einzelne Aufgabe irgendwo bei 150 bis 500 Wörtern. Liegen Sie deutlich darüber, prüfen Sie, ob Sie zwei Aufgaben zusammengeklebt haben oder in eine Erklärung der Philosophie der Funktion abgedriftet sind.
Die Ausnahme sind Einrichtungsanleitungen wie „Shopify-Shop verbinden“, bei denen es wirklich ein Dutzend Schritte in zwei Systemen gibt. Die dürfen lang sein, solange Sie sie in H2-Abschnitte gliedern, zu denen man springen kann.
Wo Screenshots helfen und wo sie schaden
Screenshots bemerken Leser am meisten, und Teams pflegen sie am wenigsten.
Setzen Sie einen dort ein, wo die Oberfläche mehrdeutig ist: eine überfüllte Einstellungsseite, ein Dialog mit sechs Feldern, eine Schaltfläche, die nicht dort ist, wo Menschen sie erwarten. Verzichten Sie bei „Klicken Sie auf Speichern“ darauf. Schneiden Sie eng auf den relevanten Bereich zu und markieren Sie das Ziel, wenn der Bildschirm unruhig ist.
Der Haken: Jeder Screenshot ist ein Versprechen, dass die Oberfläche noch so aussieht. Verschieben Sie ein Menü, und Dutzende Artikel zeigen Kunden stillschweigend eine Seite, die es nicht mehr gibt. Das ist das Hauptargument dafür, sie zu automatisieren, statt sie von Hand aufzunehmen. Wir haben die Optionen (Playwright-Skripte, Bildschirmrekorder, Tools, die sie für Sie aufnehmen) in Produkt-Screenshots automatisch erstellen verglichen.

Was Sie zuerst schreiben sollten
Wenn Sie bei null anfangen, versuchen Sie nicht, jede Funktion zu dokumentieren. Schreiben Sie in dieser Reihenfolge:
- Die ersten fünfzehn Minuten. Registrierung, der erste Einrichtungsschritt, der erste „Ach, das ist nützlich“-Moment. Diese Artikel liest jeder neue Nutzer.
- Ihre häufigsten Support-Fragen. Gehen Sie Ihren Posteingang durch. Alles, was Sie diesen Monat dreimal beantwortet haben, bekommt einen Artikel.
- Alles, was Geld oder Daten betrifft. Änderungen bei der Abrechnung, Kündigen, Löschen, Exportieren. Hier sind Menschen nervös und wollen Gewissheit, keinen vagen Absatz.
- Integrationen. Beim Verbinden von Drittkonten bleiben Menschen an Seiten hängen, die Sie nicht kontrollieren.
- Alles andere, grob danach geordnet, wie oft Menschen darauf stoßen.
Gruppieren Sie sie in eine Handvoll Sammlungen, die so heißen, wie Kunden denken: „Erste Schritte“, „Abrechnung und Konto“, „[Ihre Kernfunktion] nutzen“, „Integrationen“, „Fehlerbehebung“. Vermeiden Sie Sammlungen, die die Struktur Ihrer internen Teams spiegeln.

Hilfedokumente schreiben: kleine Gewohnheiten, die sich summieren
- Schreiben Sie in der zweiten Person und im Präsens: „Klicken Sie“, „Sie sehen“.
- Verwenden Sie die echten Beschriftungen des Produkts, auch wenn Sie sie für schlecht gewählt halten. Gehen Sie danach los und korrigieren Sie die Beschriftung.
- Halten Sie Absätze auf zwei oder drei Sätze.
- Setzen Sie Hinweisboxen sparsam ein. Ein Hinweis für etwas Nützliches, eine Warnung für etwas Unumkehrbares. Wenn jeder Artikel drei Warnungen hat, nimmt niemand sie mehr wahr.
- Zeigen Sie, wann der Artikel zuletzt aktualisiert wurde, damit Leser (und Sie) erkennen, wie aktuell er ist.
- Verlinken Sie nach vorn. Jeder Artikel sollte auf das verweisen, was Menschen üblicherweise als Nächstes tun.
Der Styleguide für Entwicklerdokumentation von Google richtet sich an technische Dokumentation, aber das meiste seiner Ratschläge zu Klarheit und Ton funktioniert genauso gut für kundenorientierte Hilfe.
Der Teil, den niemand einplant: Artikel korrekt halten
Den Artikel zu schreiben ist der leichte Teil. Das Schwierige ist, dass sich Ihr Produkt jede Woche ändert und Ihr Help-Center nicht.
Welches Werkzeug Sie auch nutzen, ein paar Dinge helfen:
- Versehen Sie jeden Artikel mit der Funktion oder Seite, die er behandelt, damit Sie bei einer Änderung genau wissen, welche Artikel zu prüfen sind.
- Machen Sie „Doku geprüft“ zum Teil der Definition of Done für jeden PR, der Texte der Oberfläche oder einen Nutzerablauf ändert.
- Lesen Sie Ihre meistbesuchten Artikel etwa einmal im Monat erneut. Dort richtet ein veralteter Screenshot den größten Schaden an.
- Achten Sie auf Suchanfragen ohne Treffer. Das ist eine kostenlose Liste von Artikeln, die Sie noch nicht geschrieben haben.
Das behandeln wir ausführlich in Dokumentation aktuell halten, einschließlich der Frage, wie Sie die Prüfung der Dokumentation an Ihren Release-Prozess koppeln. Und wenn Sie Release Notes veröffentlichen, gilt dieselbe Disziplin dort: siehe Changelog schreiben, den Kunden wirklich lesen.
Wo Ellie Docs ins Spiel kommt
Offenlegung: Wir bauen ein Tool dafür. Ellie Docs verbindet sich mit Ihrem GitHub-Repository, liest den Code, um Ihre Funktionen und nutzersichtbaren Seiten zu ermitteln, und entwirft ein vollständiges Help-Center. Es startet Ihre App in einer Sandbox, nimmt echte Screenshots des angemeldeten Produkts auf und platziert sie in den Artikeln.

Der Teil, der mir am wichtigsten ist, ist die Pflege. Wird ein PR gemergt, prüft Ellie, welche Artikel von der Änderung betroffen sind, und schlägt Änderungen als Diff vor, den Sie annehmen oder verwerfen. Nichts wird von allein veröffentlicht. Sie entscheiden weiterhin, was Kunden lesen, Sie erfahren nur nicht mehr durch ein Support-Ticket, dass Schritt 6 seit einem Monat falsch ist.
Wenn Sie schon ein Help-Center haben, importiert es Ihre bestehenden Artikel als Entwürfe, sodass Sie nicht bei null anfangen. Es gibt einen kostenlosen Tarif, ohne Karte.
Und wenn Sie lieber alles von Hand machen: Die obige Vorlage funktioniert auch allein gut.
Ein paar Fragen, die Menschen stellen
Was ist der Unterschied zwischen einem Help-Center und einer Wissensdatenbank? In der Praxis nicht viel. „Wissensdatenbank“ meint meist die Sammlung der Artikel, „Help-Center“ die kundenorientierte Seite mit Suche und Navigation darüber. Die meisten Tools verwenden die Begriffe synonym.
Wer sollte Hilfeartikel schreiben: Support, Produkt oder Entwicklung? Wer den Fragen am nächsten ist. Der Support weiß, was Menschen verwirrt, die Entwicklung weiß, was sich geändert hat. Gut funktioniert ein Aufbau, in dem der Support das Help-Center verantwortet und Entwickler betroffene Artikel in ihren PRs markieren.
Möchten Sie einen ersten Entwurf Ihres Help-Centers aus Ihrer eigenen Codebasis? Testen Sie Ellie Docs kostenlos und sehen Sie, was es aus Ihrem Repository erzeugt.