Dokumentation aktuell halten, wenn Sie jede Woche ausliefern

von Fraser Hardy

Ein gemergter Pull Request mit roten und grünen Diff-Zeilen und ein Pfeil in einen Hilfeartikel, in dem der passende Schritt zur Prüfung hervorgehoben ist, mit den Schaltflächen zum Annehmen und Verwerfen

Ein Kunde schreibt: „In Ihrer Anleitung steht, ich soll zu Einstellungen und dann zu Kalender gehen. Einen Kalender gibt es nicht.“ Er hat recht. Sie haben ihn vor sechs Wochen nach Konten verschoben. Der PR wurde geprüft, getestet und ausgeliefert. Der Hilfeartikel blieb unverändert, weil es niemandes Aufgabe war, ihn zu ändern.

So entsteht fast jede veraltete Dokumentation. Nicht aus Faulheit, sondern weil die Verbindung zwischen „Wir haben das Produkt geändert“ und „Diese Artikel beschreiben den Teil, den wir geändert haben“ fehlt.

Um die Dokumentation aktuell zu halten, wenn Sie jede Woche ausliefern, machen Sie die Doku zum Teil des Pull Requests: Jeder PR beantwortet „Ändert das, was ein Kunde sieht?“, nennt die betroffenen Hilfeartikel und liefert die Doku-Änderung im selben PR oder in einem verknüpften mit. Automatisieren Sie dann die mechanischen Teile (Screenshots, Changelog-Einträge) und beobachten Sie Support-Tickets und Suchanfragen im Help-Center auf Abweichungen, die durchrutschen.

Der Rest dieses Beitrags zeigt, wie Sie das einrichten, ohne einen technischen Redakteur einzustellen.

Warum Dokumentation veraltet

Das Auseinanderdriften der Doku hat ein paar vorhersehbare Ursachen, und keine davon löst sich mit „Lasst uns sorgfältiger sein“.

Die Doku liegt woanders. Der Code liegt in GitHub. Die Doku liegt in Intercom, Zendesk, Notion oder einem GitBook-Space. Nichts verbindet eine Datei im einen mit einer Seite im anderen, sodass eine Änderung an dem einen nie einen Blick auf das andere auslöst.

Wer es weiß, schreibt nicht. Der Entwickler, der die Kalendereinstellungen verschoben hat, weiß genau, was sich geändert hat. Wer das Help-Center pflegt, erfährt es von einem Kunden.

Die Doku wird in Schüben korrigiert. „Wir machen am Quartalsende einen Doku-Durchgang.“ In der Zwischenzeit nagt jedes wöchentliche Release an der Genauigkeit, und die große Überarbeitung dauert so lange, dass sie bei der Fertigstellung schon teilweise veraltet ist.

Niemand weiß, welche Artikel betroffen sind. Selbst ein motiviertes Team kann nach jedem Release keine 80 Artikel prüfen. Also prüft es keinen.

Illustratives Diagramm zum Auseinanderdriften der Dokumentation im Zeitverlauf: Eine Linie für die vierteljährliche Überarbeitung fällt nach jedem wöchentlichen Release ab und springt erst bei der Überarbeitung zurück, während eine Linie für Updates pro PR die ganze Zeit nahe an der Korrektheit bleibt

Das Muster ist dasselbe wie bei jeder anderen Wartungsarbeit. Kleine, kontinuierliche Updates schlagen periodische Kraftakte.

Machen Sie die Doku zum Teil der Definition of Done

Die wirksamste einzelne Änderung: Ergänzen Sie Ihre Pull-Request-Vorlage um einen Doku-Abschnitt. GitHub füllt ihn bei jedem PR vor, wenn Sie eine Datei unter .github/pull_request_template.md ablegen (GitHubs Anleitung zu PR-Vorlagen).

## Docs impact

- [ ] This changes something a customer can see or do
- Help articles affected: <!-- slugs or links, or "none" -->
- [ ] Screenshots need re-capturing
- [ ] Changelog entry drafted (or marked "internal only")

Eine Pull-Request-Vorlage mit einem Abschnitt „Docs impact“: Kontrollkästchen dafür, ob die Änderung für Nutzer sichtbar ist, welche Hilfeartikel sie berührt, ob Screenshots neu aufgenommen werden müssen und ob ein Changelog-Eintrag entworfen ist

Etwa zwei Wochen lang fühlt sich das nach Bürokratie an. Dann wird es der Moment, in dem ein Entwickler sagt: „Ach, der Onboarding-Artikel erwähnt diese Seite“, solange der Kontext noch frisch ist. Eine zweizeilige Doku-Korrektur von der Person, die die Änderung gemacht hat, ist besser als eine perfekte, die einen Monat später aus Vermutungen entsteht.

Zwei Regeln sorgen dafür, dass es hält:

  1. Reviewer prüfen das Kästchen. Wenn ein PR offensichtlich die Oberfläche ändert und „no docs impact“ sagt, fragt der Reviewer nach dem Grund. Genau wie bei einem fehlenden Test.
  2. Die Doku-Änderung darf grob sein. Entwickler müssen keine geschliffene Prosa schreiben. „Schritt 6 jetzt: Konten öffnen, dann Verfügbarkeitseinstellungen“ genügt. Jemand kann die Formulierung später glätten. Erst die Genauigkeit.

Ordnen Sie Hilfeartikel dem Code zu, den sie beschreiben

Die PR-Checkliste verlässt sich darauf, dass Menschen wissen, welche Artikel es gibt. Helfen Sie nach mit einer einfachen Zuordnung von Code-Pfaden zu Artikeln:

# docs-map.yml
- paths: ["src/features/calendar/**", "src/pages/accounts/availability*"]
  articles: ["connect-your-calendar", "set-your-availability"]
- paths: ["src/features/billing/**"]
  articles: ["change-your-plan", "update-payment-method", "download-invoices"]
- paths: ["src/features/onboarding/**"]
  articles: ["get-started"]

Dann liest ein kleiner CI-Schritt die Liste der geänderten Dateien (git diff --name-only origin/main...HEAD), gleicht sie mit den Globs ab und postet einen Kommentar im PR: „Dieser PR berührt Kalender-Code. Prüfen: connect-your-calendar, set-your-availability.“ Das sind vielleicht 40 Zeilen Skript, und aus „Denk an die Doku“ wird eine konkrete, anklickbare Liste.

Die Zuordnung veraltet natürlich auch. Halten Sie sie neben dem Code und ergänzen Sie eine Zeile, sobald jemand einen neuen Artikel schreibt. Sie ist trotzdem viel leichter zu pflegen als die Doku selbst.

Wenn Ihre Doku im selben Repository liegt (Docs-as-Code mit etwas wie Docusaurus, Mintlify oder Git Sync von GitBook), können Sie weitergehen: Ein CODEOWNERS-Eintrag für den Doku-Ordner stellt sicher, dass jemand, dem die Doku am Herzen liegt, jede Änderung daran prüft.

Schreiben Sie Doku, die langsamer verrottet

Manche Schreibentscheidungen erleichtern die Pflege der Dokumentation erheblich:

Mehr zur Struktur in unserem Leitfaden zum Schreiben von Hilfeartikeln, die Menschen wirklich nutzen.

Automatisieren Sie die mechanischen Teile

Manche Doku-Pflege ist Urteilsvermögen. Vieles davon sind schlicht Pflichten, die ein Skript besser erledigt.

Screenshots. Bilder von Hand neu aufzunehmen ist das Erste, was sich automatisieren lässt. Ein Playwright-Skript gegen ein vorbereitetes Demo-Konto, ausgeführt in der CI, liefert bei jedem Merge frische, konsistente Bilder. Das vollständige Skript gehen wir in Produkt-Screenshots automatisch erstellen durch.

Changelog-Einträge. Ihre gemergten PRs beschreiben bereits, was ausgeliefert wurde. Sie in einen kundenorientierten Changelog zu verwandeln heißt vor allem, Entwicklersprache in klare Sprache umzuschreiben und nach Added, Changed und Fixed zu gruppieren, der von Keep a Changelog bekannt gemachten Konvention. Vorlagen finden Sie in Changelog schreiben, den Kunden lesen.

Videos. Wenn Sie Walkthrough-Videos haben, sagt dieselbe Zuordnung von Code-Pfaden, welche neu aufgenommen werden müssen. Bild und Ton getrennt aufzunehmen macht die Wiederholung schnell, hier ist der Ablauf für Produkt-Walkthrough-Videos.

Finden Sie die Abweichungen, die Sie schon haben

Auch bei gutem Prozess rutschen manche Änderungen durch. Diese Signale zeigen, wo:

Dokumentieren Sie nicht, was noch nicht ausgeliefert ist

Eine Falle für schnelle Teams: Ein PR wird hinter einem Feature-Flag gemergt, jemand aktualisiert gewissenhaft die Doku, und nun beschreibt das Help-Center eine Funktion, die die meisten Kunden nicht sehen. Kunden sind verwirrt, und der Support bekommt die Tickets.

Halten Sie Doku-Änderungen für Arbeit hinter Flags zurück, bis das Flag für alle aktiv ist (oder schreiben Sie sie als Entwürfe und veröffentlichen Sie sie mit dem Rollout). Dasselbe gilt für Changelog-Einträge.

Tools, die bei der Pflege der Dokumentation helfen

Helpdesks wie Intercom, Zendesk und Help Scout haben völlig brauchbare Editoren für das Help-Center, aber sie wissen nicht, was in Ihrem Code steht, also bleibt die ganze Verknüpfung oben an Ihnen hängen. Docs-as-Code-Plattformen wie GitBook und Mintlify halten die Doku in Git, was Ihnen PR-Review und Historie bringt, und funktionieren am besten, wenn Ihre Autoren in einem Repository zu Hause sind. Neuere KI-first-Tools für das Help-Center, darunter Ferndesk, versuchen die Lücke aus anderen Richtungen zu schließen.

Wir haben Ellie Docs gezielt rund um die Verbindung zum PR gebaut. Sie verbinden ein GitHub-Repository, und Ellie ordnet Ihre Funktionen zu und verknüpft jeden Hilfeartikel mit den Funktionen, die er beschreibt. Bei jedem gemergten PR prüft es, welche Artikel von der Änderung betroffen sind, und schlägt Änderungen als prüfbaren Diff vor, mit einer kurzen Begründung. Sie nehmen jeden an oder verwerfen ihn. Nichts wird von allein veröffentlicht.

Ellie Docs schlägt ein Update für den Artikel „Connect your calendar and preview availability“ nach einem gemergten PR vor: der veraltete Schritt rot durchgestrichen, die neuen Schritte grün, dazu die Schaltflächen „Accept“ und „Dismiss“

Es entwirft außerdem Changelog-Einträge aus denselben gemergten PRs und hält alles zurück, was noch hinter einem Flag liegt, bis es veröffentlicht ist.

Die Changelog-Seite von Ellie Docs mit Einträgen, die aus gepushtem Code entworfen wurden, darunter ein neues Panel für Verfügbarkeitseinstellungen, jeweils mit dem zugehörigen Hilfeartikel verknüpft und bereit zur Veröffentlichung

Sie können alles in diesem Beitrag von Hand erledigen, und viele Teams tun das. Ellie übernimmt nur den Teil „Welche Artikel betrifft dieser PR, und was sollte sich ändern?“, jedes Mal für Sie.

Häufige Fragen

Wer sollte in einem kleinen Team für die Dokumentation zuständig sein? Eine namentlich benannte Person verantwortet das Help-Center insgesamt (oft die Gründerin oder wer den Support übernimmt), aber jeder Entwickler verantwortet die Doku-Auswirkungen seiner eigenen PRs. Geteilte Verantwortung ohne benannte Person bedeutet: keine Verantwortung.

Wie oft sollten wir unsere Doku überprüfen? Laufend bei Änderungen (über die PR-Checkliste), dazu monatlich ein Durchklicken Ihrer meistgesehenen Artikel. Große vierteljährliche Überarbeitungen sind ein Zeichen dafür, dass der laufende Teil nicht stattfindet.

Lohnt sich Docs-as-Code für Hilfedokumente für Kunden? Wenn die Schreibenden Entwickler sind, ja. Wenn Support oder Marketing das meiste schreiben, funktioniert ein normaler Editor für das Help-Center plus PR-Checkliste und Doku-Zuordnung meist besser, als alle in Git zu zwingen.

Was ist der schnellste Gewinn, wenn unsere Doku schon stark veraltet ist? Korrigieren Sie die 10 meistgenutzten Artikel, führen Sie die PR-Vorlage ein und beginnen Sie, Support-Tickets zu markieren, die die Doku erwähnen. Das stoppt den Blutverlust, bevor Sie sich den langen Schwanz vornehmen.

Wenn Sie die Doku-Änderungen lieber bei jedem PR vorgeschlagen bekommen möchten, testen Sie Ellie Docs kostenlos. Verbinden Sie ein Repository, erhalten Sie ein entworfenes Help-Center und prüfen Sie Änderungsvorschläge, während Sie ausliefern.