Dokumentation schreiben, die Entwickler wirklich lesen

Die meiste Dokumentation wird einmal geschrieben, selten gelesen und mit jedem Monat weniger ernst genommen. Wir bauen gerade unsere eigene Doku um und haben dabei die Gewohnheiten gesammelt, die dafür sorgen, dass eine Seite bis zum Ende gelesen wird.

Beginnen Sie mit etwas, das läuft

Entwickler kommen mit einer Aufgabe, nicht aus Neugier. Das Erste auf der Seite sollte das kleinste Beispiel sein, das die Aufgabe erledigt, bereit zum Kopieren.

curl https://api.example.com/v1/health \
  -H "Authorization: Bearer $API_KEY"

Erklären Sie es danach. Ein Absatz Hintergrund vor dem ersten Snippet ist die Stelle, an der Leser abspringen.

Halten Sie Seiten kurz und auf einen Zweck beschränkt

Eine Seite, die eine Frage beantwortet, lässt sich finden, verlinken und aktuell halten. Eine Seite, die sechs beantwortet, wird zur Wand, die niemand pflegt.

Ein nützlicher Längentest

Wenn die Seite ein Inhaltsverzeichnis braucht, um navigierbar zu sein, sollte sie wahrscheinlich zwei Seiten sein.

Schreiben Sie Beispiele mit echten Werten

foo und bar verraten nichts darüber, was ein Feld enthält. Verwenden Sie eine plausible Job-ID, ein tatsächliches Datumsformat, einen realistischen Fehler-Body. Leser lernen die Form Ihrer Daten eher aus den Beispielen als aus dem Schema.

Zeigen Sie die Fehlerfälle

Jede API-Seite sollte mindestens eine Fehlerantwort enthalten und sagen, was dann zu tun ist. Support-Tickets entstehen meist dort, wo Menschen auf den Pfad geraten, den die Doku nie gezeigt hat.

Machen Sie die Suche tolerant gegenüber Tippfehlern und Synonymen

Menschen suchen nach dem, was sie tun wollen, nicht nach dem, wie Sie es genannt haben. Sie tippen „login“, wenn Ihre Seite „authentication“ heißt. Ergänzen Sie Aliasse im Frontmatter der Seite und prüfen Sie monatlich Ihre Such-Logs auf Anfragen ohne Treffer; jede steht für eine fehlende Seite oder ein fehlendes Synonym.

title: Authentication
aliases:
  - login
  - api key
  - sign in

Halten Sie die Doku beim Code

Doku, die im selben Repository wie der Code liegt, wird im selben Pull Request aktualisiert. Das ist die Idee hinter DocsFlowy, das wir gerade bauen: auf das Markdown eines Repositorys verweisen und daraus eine durchsuchbare Website veröffentlichen. Mehr dazu, sobald es etwas zum Ausprobieren gibt.

Eine kurze Checkliste

• Enthält der erste Bildschirm etwas Kopierbares?
• Hat diese Seite einen klaren Zweck?
• Sind die Beispielwerte realistisch?
• Wird der Fehlerfall gezeigt?
• Findet man sie über das Wort, das ein Neuling verwenden würde?