Docsbook
Übersicht

Warum wir Notion für die Produktdokumentation nicht mehr verwenden

Früher habe ich alles in Notion abgelegt. Internes Handbuch, Produktspezifikationen, kundenorientierte FAQ, API-Beispiele, das Runbook für den Bereitschaftsdienst, das Changelog, den halbfertigen Onboarding-Leitfaden, den niemand gelesen hat. Ein Arbeitsbereich, ein Suchfeld, ein Berechtigungssatz. Etwa achtzehn Monate lang fühlte sich das großartig an.

Dann versuchten wir, mehr Traffic auf die Dokumentation zu bringen. Danach versuchten wir, eine zweite Sprache hinzuzufügen. Und dann fragte ein Kunde, warum die Seite, die er gerade las, beim API drei Releases hinterherhinkte. Als ich schließlich alles aus Notion migriert hatte, besaß ich eine Liste von Fehlern, von denen ich mir gewünscht hätte, jemand hätte sie mir am ersten Tag mitgegeben.

Das ist diese Liste. Es ist keine Abrechnung — Notion ist wirklich ein gutes Produkt für das, wofür es entwickelt wurde. Dies ist ein Beitrag über den spezifischen Moment, in dem ein „gutes Wiki“ keine „gute Dokumentation“ mehr ist, und darüber, wie man diesen Moment erkennt, bevor man 400 Seiten und ein Vertriebsteam hat, das darauf angewiesen ist, dass die Dokumentation tatsächlich ein gutes Ranking erzielt.

Wo ist Notion noch überlegen?#

Bevor die Beschwerden kommen: der ehrliche Teil.

Notion ist das beste Tool, das ich je für gemeinsames Denken verwendet habe. Strategiedokumente, Besprechungsnotizen, RFCs im Entwurf, Produktspezifikationen, über die sich vier Personen in den Kommentaren streiten – Notion ist die richtige Wahl. Das Blockmodell, die Datenbankansichten, die Inline-Datenbanken, die verknüpften Erwähnungen, die Tatsache, dass jeder, auch ohne technische Kenntnisse, etwas bearbeiten kann, ohne etwas kaputtzumachen – all das ist real und nur schwer nachzubilden.

Wenn deine Dokumente vollständig innerhalb des Unternehmens bleiben und nie um die Aufmerksamkeit eines Fremden bei Google konkurrieren müssen, ist Notion in Ordnung. Wenn dein Publikum aus vierzig Personen besteht, die alle deinen Notion-Login haben, betrifft dich dieser Beitrag nicht. Schließe den Tab und geh etwas Nützliches schreiben.

Im weiteren Verlauf dieses Beitrags geht es um den Moment, in dem die Dokumente das Gebäude verlassen.

1. Die Suche ist zwei verschiedene Probleme, und Notion löst eines davon#

Die interne Suche von Notion ist hervorragend. Cmd+K, unscharfe Übereinstimmungen über Titel hinweg, direkt zur Seite springen. Das ist die Suche, die für Entwickler wichtig ist, und Notion hat sie gut umgesetzt.

Die Suche, die Kunden wichtig ist, findet auf Google, ChatGPT und Perplexity statt. Und bei dieser Suche ist Notion standardmäßig hinderlich. Seiten werden über JavaScript geladen, das HTML ist größtenteils leer, bis React die Inhalte übernimmt, interne Links führen über notion.so/<hash>-Weiterleitungen, Überschriften werden häufig mit nicht semantischem Markup gerendert, und die URLs sehen aus wie notion.site/Getting-Started-9f8a3b2c1d4e. Google kann die Inhalte crawlen, aber das SEO-Ergebnis ist durchweg schlechter als bei denselben Inhalten als einfaches Markdown auf einer normalen Domain.

Als uns ein Wettbewerber mit objektiv schlechteren Inhalten zum ersten Mal überholte, weil er Markdown geschrieben und eine Sitemap veröffentlicht hatte, wurde mir die Lektion klar. Dokumentation für Kunden ist eine SEO-Fläche. Sie muss auch so behandelt werden. Ein Wiki ist keine SEO-Fläche.

2. Versionskontrolle, die keine Versionskontrolle ist#

Notion verfügt über einen Seitenverlauf. Es ist Git. Der Unterschied ist wichtiger, als ich erwartet hatte.

Ich kann zwei Versionen eines Dokuments nicht in einem Code-Review vergleichen. Ich kann nicht fragen: „Was hat sich zwischen v1.4 und v1.5 im Authentifizierungsabschnitt geändert?“ und eine klare Antwort erhalten. Ich kann eine Änderung an der Dokumentation nicht in denselben Pull Request aufnehmen wie die Codeänderung, die sie dokumentiert, sodass die Dokumentation immer leicht hinterherhinkt. Ich kann einen Junior-Entwickler nicht bitten, die API-Referenz als Teil desselben PRs zu aktualisieren, mit dem die API ausgeliefert wird, weil die Dokumentation in einem anderen System mit anderen Berechtigungen und einem anderen mentalen Modell liegt.

Das Ergebnis ist eine Abweichung zwischen Dokumentation und Code. Der Code wird am Montag ausgeliefert, das Dokument am Donnerstag aktualisiert, und am Mittwoch liest ein Kunde die alte Version und erstellt ein Support-Ticket. Das wiederholt sich bei jedem Release. Die Lösung besteht nicht darin, die Leute daran zu erinnern, Notion zu aktualisieren. Die Lösung besteht darin, die Dokumentation neben dem Code abzulegen, sodass „der Code wurde ausgeliefert, aber die Dokumentation nicht“ etwas ist, worauf die Diff-Tools lautstark hinweisen können.

Nachdem ich Dokumentation in einem Repository mit PR-Vorlagen hatte, wurden Aktualisierungen der Dokumentation Teil der Definition of Done und keine nachträgliche Überlegung mehr. Diese eine Änderung des Arbeitsablaufs hat mehr für die Aktualität der Dokumentation bewirkt als jedes Tool.

3. Mehrsprachigkeit ist kein Feature, sondern eine Architektur#

Wir haben einmal versucht, unsere Notion-Dokumentation zu internationalisieren. Der Plan war vernünftig: den Workspace duplizieren, übersetzen und über einen Sprachumschalter verlinken. Innerhalb eines Monats war sie nicht mehr wartbar.

Die tatsächlichen Kosten mehrsprachiger Dokumentation liegen nicht in der Übersetzung. Sie liegen in der Kopplung zwischen den Sprachen. Wenn sich die englische Version ändert, ist jede Übersetzung veraltet, und du brauchst ein System, das dies erkennt. Du brauchst:

  • Eine kanonische Quelle, damit Übersetzer wissen, von welcher Version sie übersetzen.
  • Eine Möglichkeit, eine Übersetzung als veraltet zu markieren, wenn sich die Quelle ändert.
  • hreflang-Tags, damit Google weiß, dass die spanische Seite die spanische Version der englischen Seite und kein Duplikat ist.
  • Eine URL pro Sprache mit vorhersehbaren Pfaden (/es/getting-started, /de/getting-started).
  • Eine Möglichkeit, eine teilweise Übersetzung zu veröffentlichen – einige Seiten in fünf Sprachen, andere in zwei –, ohne die Navigation zu beschädigen.

Notion kann nichts davon. Am Ende hast du fünf voneinander getrennte Workspaces und eine Google-Tabelle, in der festgehalten wird, was nicht mehr synchron ist. Die Google-Tabelle funktioniert etwa drei Wochen lang, dann geben alle auf.

Wenn du irgendwann Dokumentation in mehr als einer Sprache veröffentlichen willst, solltest du nicht mit Notion anfangen. Der Migrationsaufwand wächst linear mit der Seitenanzahl, und der damit verbundene Schmerz wächst überproportional.

4. KI-Crawler können Ihr Wiki nicht lesen#

Das ist der neue Punkt – und der, den ich unterschätzt habe.

Bis 2026 erreicht ein bedeutender Anteil der Fragen „Wie funktioniert X?“ nie Ihre Website. Der Nutzer fragt ChatGPT, Claude oder Perplexity, und die Antwort wird aus dem synthetisiert, was diese Modelle sehen können. Mintlify hat den Datenverkehr über 30 Tage hinweg auf den von ihm gehosteten Dokumentationsseiten gemessen – etwa 790 Millionen Anfragen – und berichtet, dass KI-Coding-Agenten 45,3 % aller Anfragen ausmachten, wobei Claude Code 25,2 % und Cursor 18,0 % erreichten (Der Stand des Agentenverkehrs in der Dokumentation, veröffentlicht am 3. April 2026). Eine Folgemessung ergab, dass der Anteil der Agenten im Juli 2026 bei 66 % des Datenverkehrs lag (Bericht zur Jahresmitte 2026, veröffentlicht am 29. Juli 2026). Das ist die Flotte eines einzelnen Anbieters und nicht das gesamte Web, aber es handelt sich um die größte veröffentlichte Messung des Agentenverkehrs zu Dokumentationen. Unsere eigenen Zahlen sind niedriger und entwickeln sich in dieselbe Richtung.

Damit ein KI-Crawler Ihre Dokumentation zitieren kann, muss er Ihre Dokumentation lesen können. Das bedeutet sauberes serverseitig gerendertes HTML, semantische Überschriften, eine sitemap.xml, idealerweise eine llms.txt, die den kanonischen Inhalt auflistet, sowie eine Allow für die wichtigsten KI-User-Agents in robots.txt. Notion bietet davon so gut wie nichts. Das HTML ist stark JavaScript-lastig, es gibt keine llms.txt, und die empirische Antwortrate für KI-Crawler ist schlecht.

Wenn Sie in einer Antwortmaschine zitiert werden möchten, muss Ihre Dokumentation für einen Crawler wie eine Dokumentationswebsite aussehen. Sie darf nicht wie eine SPA wirken, die um eine Datenbankansicht herum aufgebaut ist.

5. Das Performance-Budget für Dokumentation ist brutal#

Eine Dokumentationsseite sollte sich sofort laden. Das ist keine stilistische Präferenz – es ist ein Hebel für Conversions. Der Nutzer versucht um 2 Uhr morgens, einen Fehler zu beheben, ist ohnehin schon frustriert, und jede Sekunde Ladezeit ist eine Chance für ihn, aufzugeben und stattdessen ein Ticket zu erstellen.

Führe eine von Notion veröffentlichte Seite durch Lighthouse. Die Zahlen sind nicht besonders gut. Der Largest Contentful Paint liegt über eine echte Mobilfunkverbindung normalerweise im Bereich von 3–5 Sekunden, der Cumulative Layout Shift ist bemerkbar, weil der React-Baum in Wellen hydratisiert wird, und die Total Blocking Time ist hoch, weil viel JavaScript geparst werden muss.

Bei einem internen Wiki interessiert das niemanden. Bei einer kundenorientierten Dokumentation, die mit tausend anderen geöffneten Tabs konkurrieren muss, ist das sehr wichtig. Wir haben festgestellt, dass die Absprungrate auf Dokumentationsseiten deutlich gesunken ist, als wir auf statisch gerendertes Markdown umgestiegen sind. Das ist eine dieser Zahlen, die man, sobald man sie einmal gesehen hat, nicht mehr ungesehen machen kann.

6. Die Bindung ist real und verstärkt sich#

Notion bietet einen Export. Ich habe ihn verwendet. Das Ergebnis ist ein Ordner mit HTML- oder Markdown-Dateien mit verstümmelten Dateinamen, fehlerhaften internen Links, die auf notion.so-URLs verweisen, eingebetteten Datenbanken, die zu unlesbaren Tabellen abgeflacht werden, und Bildverweisen, die auf signierte S3-URLs zeigen, die ablaufen. 400 Seiten zu exportieren und den Export anschließend zu reparieren, ist eine Arbeitswoche.

Die Bindung hängt nicht davon ab, ob eine Export-Schaltfläche vorhanden ist. Es geht darum, ob die exportierten Daten strukturiert genug sind, um in einem anderen Tool ohne eine Portierung nützlich zu sein. Nach diesem Maßstab sind Notion-Exporte schwach. Je länger man bleibt, desto mehr Seiten sammelt man an und desto höher steigen die Migrationskosten. Man bemerkt es erst, wenn man versucht zu gehen.

Markdown in einem Git-Repository hat die gegenteilige Eigenschaft. Der „Export“ ist git clone. Du kannst das Verzeichnis in jeden anderen Generator für statische Websites oder auf jede andere Dokumentationsplattform verschieben oder es einfach als unveränderte Dateien veröffentlichen. Diese Portabilität ist die am meisten unterschätzte Eigenschaft, die ein Dokumentationssystem haben kann. Sie erscheint erst dann wertvoll, wenn man sie braucht – und dann ist sie alles wert.

7. Berechtigungen, Entwürfe und die Trennung von Wiki und Dokumentation#

Das tiefgreifendste Problem besteht darin, dass Wikis und Dokumentationen unterschiedliche Produkte sind, die im Editor zufällig gleich aussehen.

Ein Wiki ist für uns. Es enthält Entwürfe, halbfertige Seiten, ausschließlich interne Abschnitte, Seiten, bei denen sich zwei Teamleiter in den Kommentaren uneinig sind, Runbooks, die niemals öffentlich sein sollten, und einen „Archiv“-Ordner, der in Wirklichkeit nur der Ort ist, an dem Dinge in Vergessenheit geraten. Das Berechtigungsmodell ist granular, weil das Publikum granular ist.

Dokumentationen sind für sie. Es gibt eine veröffentlichte Version, keine Zwischenstadien, keine für Leser sichtbaren Entwürfe und keine von der öffentlichen URL aus sichtbaren Kommentar-Threads. Entwürfe befinden sich in Pull Requests, nicht im Produktionsbaum. Das Berechtigungsmodell ist binär – veröffentlicht oder nicht –, weil das Publikum das gesamte Internet ist.

Notion wurde für die erste Aufgabe entwickelt und für die zweite angepasst. Am Ende hat man einen Workspace, der interne Handbuchseiten und kundenorientierte API-Dokumentation im selben Baum vermischt, und ein Konfigurationsfehler macht die falsche Seite öffentlich. Ich habe das bei drei Unternehmen erlebt und es selbst beinahe getan.

Die Grenze zwischen „Wiki“ und „Dokumentation“ sollte physisch gezogen werden. Anderes System, anderes Repository, anderer Review-Workflow, andere Domain.

Was verwenden wir stattdessen?#

Für interne Inhalte, die Kommentare, Meinungen, Entwürfe und Inline-Datenbanken benötigen – Strategiedokumente, RFCs, Besprechungsnotizen, das Handbuch – ist Notion nach wie vor das richtige Tool. Wir haben nicht aufgehört, Notion zu verwenden. Wir haben nur aufgehört, es für die falsche Aufgabe zu verwenden.

Für kundenseitige Dokumentation liegen die Dokumente in einem Git-Repository, werden in Markdown geschrieben, per Pull Request überprüft und als statische Website veröffentlicht. Das Setup ist absichtlich unspektakulär. Die Dokumentation befindet sich neben dem Code und wird daher im selben PR aktualisiert. Die Git-Historie ist die Versionshistorie. Das Repository ist der Export. Die CI prüft Links. Die veröffentlichte Website wird serverseitig mit korrekten Überschriften, einer Sitemap, einem llms.txt und einer URL pro Sprache gerendert.

Ob du Docsbook, Docusaurus, Mintlify, VitePress oder eine eigene Lösung mit eleventy verwendest, ist eine weniger wichtige Entscheidung, als es scheint. Die größere Entscheidung wird vorher getroffen: Ist diese Dokumentation für das Team oder für die ganze Welt? Wenn sie für die ganze Welt bestimmt ist, hole sie aus dem Wiki heraus und überführe sie in ein System, das sie wie ein Produkt behandelt.

Wir haben Docsbook entwickelt, weil wir wollten, dass der Weg von „Git-Repository aus Markdown“ zu „veröffentlichte Dokumentationswebsite mit SEO, KI-Chat, fünfzehn Sprachen und Analysen“ fünf Sekunden dauert – ohne einen einzigen CI-Schritt oder docusaurus.config.js. Das ist die Version dieser Geschichte, in der wir ein Produkt zu verkaufen haben. Es ist außerdem der ehrliche Weg, den wir selbst gegangen sind. Wir haben zuerst Notion ausprobiert. Danach haben wir Docusaurus ausprobiert. Schließlich haben wir Docsbook entwickelt, weil wir die Einfachheit von Notion mit den technischen Eigenschaften einer echten Dokumentationswebsite verbinden wollten und niemand anderes dies entwickelt hatte.

Das eine Prinzip, das es wert ist, beibehalten zu werden#

Wenn deine Dokumentation von Menschen gefunden werden soll, die nicht in deinem Unternehmen arbeiten, ist sie ein Produkt für SEO und KI-Auffindbarkeit. Behandle sie auch so. Lege sie in der Versionsverwaltung ab, rendere sie als HTML, gib jeder Sprache eine echte URL und stelle sicher, dass ein Crawler sie lesen kann, ohne dein JavaScript auszuführen.

Ein Wiki ist für die Menschen, die bereits Teil des Unternehmens sind. Dokumentation ist für die Menschen, die noch draußen stehen und hineinschauen. Für diesen ersten Eindruck gibt es nur eine Chance, und er entsteht meistens um 2 Uhr morgens auf einem Smartphone, während der Leser genervt ist. Entwickle für diesen Leser, nicht für das Meeting, in dem die Dokumentation geschrieben wurde.

Das ist die Lektion. Alles andere sind Implementierungsdetails.

Kostenlos starten — keine Kreditkarte erforderlich

Nächste Schritte#

War diese Seite hilfreich?

Powered by Docsbook