Docs as Code vs. eine verwaltete Plattform: die Abwägung im Jahr 2026
„Docs as Code“ – Ihre Dokumentation lebt in Git, wird über Pull Requests überprüft und über CI bereitgestellt – ist das vorherrschende Muster bei technologieorientierten Unternehmen. „Verwaltete Plattform“ – Sie melden sich an, konfigurieren und veröffentlichen – ist das vorherrschende Muster bei designorientierten und Indie-Unternehmen. Beides funktioniert. Beides scheitert auf unterschiedliche Weise.
Das ist die ehrliche Abwägung im Jahr 2026.
Kurzfassung#
| Dokumentation als Code | Verwaltete Plattform | |
|---|---|---|
| Wo die Dokumentation liegt | Git | Datenbank der Plattform oder Git |
| Bearbeitung | Markdown in der IDE, PR-Review | Webeditor oder Markdown |
| Bereitstellung | CI/CD-Pipeline | Hochladen und vergessen |
| Hosting | Ihr eigenes | Das des Anbieters |
| Wartung | Ihre Engineering-Zeit | Die Zeit des Anbieters |
| KI-Funktionen | Sie entwickeln oder integrieren sie | Integriert |
| Kostenstruktur | Engineering-Zeit | Abonnement |
| Am besten geeignet für | Engineering-orientierte Teams, OSS, umfassende Anpassungen | Start-ups, Indie-Entwickler, „jetzt veröffentlichen“ |
Docsbook ist interessant, weil es beides vereint: Quelldateien in Git (Ihr Repository) und alles andere verwaltet.
Wann „Docs as Code“ gewinnt#
Drei Gründe, warum Docs-as-Code immer noch das richtige Muster ist:
1. Engineering lebt bereits in Git#
Wenn Ihre Dokumentationsautoren Ingenieure sind, ist der kognitive Aufwand für die Verwendung von Git für die Dokumentation gleich null. Pull Requests, Code-Reviews, Branch-Vorschauen – der gesamte bestehende Engineering-Workflow lässt sich ganz natürlich erweitern.
2. Versionierung entspricht den Code-Releases#
Dokumentationsänderungen, die zusammen mit Codeänderungen veröffentlicht werden, gehören in denselben PR. Reviewer sehen die API-Änderung und die Dokumentationsänderung zusammen. CI testet beides.
3. Umfangreiche Anpassungen sind erforderlich#
Wenn Ihre Dokumentation React-Komponenten, benutzerdefinierte Markdown-Erweiterungen oder eine Build-Pipeline benötigt, die Seiten aus Ihrer OpenAPI-Spezifikation generiert, ist Docs-as-Code mit Docusaurus, Nextra oder VitePress das richtige Muster.
Wenn eine „verwaltete Plattform“ gewinnt#
Drei Gründe, warum eine verwaltete Plattform gewinnt:
1. Dokumentationsautoren sind keine Ingenieure#
Produktvermarkter, Mitglieder des Supportteams und CS-Leads müssen häufig die Dokumentation aktualisieren. Sie aufzufordern, Markdown per PR an ein Git-Repository zu senden, erzeugt Reibung und verhindert Aktualisierungen. Ein Web-Editor ist schneller.
2. KI-Funktionen werden benötigt und Ihr Team wird sie nicht entwickeln#
Eine verwaltete Plattform, die KI-Chat, KI-Übersetzung, MCP, llms.txt und Analysen bereitstellt, bietet Ihnen jede dieser Funktionen als Schalter statt als Projekt. Jede einzelne davon ist ein echtes Projekt, wenn Sie sie selbst entwickeln: Retrieval, eine Evaluationsschleife, eine Übersetzungspipeline mit Routing pro Locale und einen Event-Store. Die meisten Teams können diesen Aufwand speziell für Dokumentationen nicht rechtfertigen.
3. Der Besitz der Deployment-Infrastruktur ist Aufwand, kein Mehrwert#
Die regelmäßig anfallende Arbeit an einer selbst gehosteten Dokumentationswebsite ist real, aber nicht planbar: Migrationen auf Hauptversionen, Abweichungen bei Abhängigkeiten und Node-Versionen, Build-Fehler, für die sich niemand verantwortlich fühlt, sowie eine Suche, die erneut genehmigt oder neu gehostet werden muss. Nichts davon liefert etwas aus, das ein Leser sehen kann.
Leiten Sie den Preis aus Ihrem eigenen Repository ab, statt von einem Durchschnittswert auszugehen: Zählen Sie die Commits an Ihrer Dokumentationsinfrastruktur in den letzten vier Quartalen, die keine Inhalte geändert haben. Diese Zahl bezeichnet genau das, was eine verwaltete Plattform entfernt.
Der Hybrid: Docsbook#
Docsbook ist ungewöhnlich, weil es sich keiner der beiden Kategorien eindeutig zuordnen lässt.
- Die maßgebliche Quelle ist Ihr GitHub-Repository (Eigenschaft von Docs-as-Code)
- Hosting, KI, Suche, Übersetzungen, Analysen und MCP werden verwaltet (Eigenschaft einer verwalteten Plattform)
- Keine CI/CD-Pipeline, kein
docusaurus.config.js, kein Swizzle (Eigenschaft einer verwalteten Plattform) - PRs und Reviews funktionieren gleich (Eigenschaft von Docs-as-Code)
- Keine Anbieterbindung — Ihre Dateien bleiben bei GitHub, wenn Sie die Plattform verlassen (Eigenschaft von Docs-as-Code)
Dieses Muster ist wichtig, weil sich die Nachteile von reinem Docs-as-Code (Bereitstellungsaufwand) und rein verwalteten Plattformen (Anbieterbindung) gegenseitig aufheben.
Kostenberechnung#
Vergleichen wir die Gesamtbetriebskosten über 24 Monate für ein typisches Startup mit 5 Ingenieuren.
Reines Docs-as-Code (Docusaurus auf Vercel)#
| Posten | Kosten über 24 Monate |
|---|---|
| Hosting auf einer kostenpflichtigen Tarifstufe | Eine wiederkehrende Rechnung, die Sie nicht bemerken werden |
| Ersteinrichtung | Entwicklungsstunden, einmalig |
| Migrationen auf Hauptversionen | Entwicklungsstunden, über zwei Jahre ungefähr zweimal |
| Vierteljährliche Wartung | Entwicklungsstunden, wiederkehrend und ungeplant |
| Erstellung eines KI-Chats | Entwicklungswochen sowie die fortlaufende Verantwortung für die Qualität der Informationsabfrage |
| Betrieb eines KI-Chats | Vektorspeicher, Embeddings und Modellaufrufe, monatlich |
| Suche (Algolia DocSearch oder selbst gehostet) | Kostenlos bei Genehmigung, andernfalls ein Abonnement oder mehr Aufwand |
| Übersetzungspipeline | Wird meist ausgelassen, da es sich um ein Projekt und nicht um einen Kostenposten handelt |
Die verwaltete Seite#
| Position | Kosten über 24 Monate |
|---|---|
| Abonnement oder nutzungsabhängige Abrechnung | Die Zahl des Anbieters – lesen Sie sie auf dessen eigener Preisseite |
| Ersteinrichtung | Unter einer Stunde |
| Wartung | Keine |
So führen Sie diesen Vergleich tatsächlich durch#
Füllen Sie beide Tabellen mit Ihren eigenen Zahlen statt mit unseren aus. Wir veröffentlichen hier bewusst keine Dollarbeträge, denn die einzigen ehrlichen Zahlen sind Ihre: Ihre Hosting-Stufe, die Vollkosten Ihrer Ingenieure, Ihr Datenverkehr.
Sobald Sie sie ausgefüllt haben, sind zwei Dinge erwähnenswert. Erstens dominieren die Arbeitsstunden der Ingenieure die Spalte für selbst gehostete Lösungen, und sie sind die Einträge, für die niemand ein Budget einplant. Zweitens ist die Zeile für die Übersetzung auf der Seite der selbst gehosteten Lösung fast immer leer – nicht weil Übersetzung wertlos wäre, sondern weil sie als Projekt nie die Hürde nimmt. Das bedeutet, dass der Vergleich nicht wirklich gleichwertig ist, sofern Sie dies nicht ausdrücklich sagen.
(Docsbook hat früher einen einmaligen PRO-Lifetime-Tarif verkauft; er wird nicht mehr angeboten, und bestehende Lifetime-Käufer behalten ihre ursprünglichen Bedingungen.)
Wenn sich die Kostenrechnung umkehrt#
Drei Szenarien, in denen Docs-as-Code günstiger ist:
- Entwicklungsstunden sind kostenlos — Sie haben einen Entwickler, der speziell mit der Dokumentationsplattform betraut ist; sein Gehalt fällt unabhängig davon ohnehin an
- Open-Source-Projekte mit Community-Beitragenden — Community-PRs übernehmen den Wartungsaufwand
- Benutzerdefinierte React-Komponenten innerhalb der Dokumentation — Dies ist auf verwalteten Plattformen nicht möglich
In diesen Fällen sind Docusaurus oder VitePress die richtige Wahl. Andernfalls spricht die Rechnung für eine verwaltete Lösung.
Anbieterbindung: So bewerten Sie sie#
Drei Fragen, die Sie jeder verwalteten Plattform stellen sollten:
- Kann ich meine Inhalte jetzt als reines Markdown exportieren? Wenn ja, ist die Anbieterbindung gering.
- Bleiben die URLs erhalten, wenn ich umziehe? Die meisten ermöglichen die Beibehaltung von URLs; einige nicht.
- Was passiert mit meiner benutzerdefinierten Domain, wenn ich kündige? Sie sollte wieder verfügbar sein.
Docsbook schneidet bei allen drei Punkten gut ab: Die Dateien befinden sich in Ihrem GitHub-Repository (Export = git clone), die URLs entsprechen den Dateipfaden (Beibehaltung = Weiterleitungen), und die benutzerdefinierte Domain ist ein DNS-Eintrag, den Sie kontrollieren.
GitBook schneidet beim ersten Punkt schlecht ab (Inhalte in deren Datenbank), bei den anderen gut. Mintlify schneidet bei allen drei Punkten gut ab.
Entscheidungsregeln#
- Engineering-orientiert, OSS, stark anpassungsorientiert → Dokumentation als Code (Docusaurus, VitePress, Nextra)
- Indie, Startup, „jetzt veröffentlichen“ → verwaltete Plattform (Docsbook, Mintlify)
- Unternehmen mit mehr als 30 Redakteuren → verwaltete Enterprise-Lösung (GitBook)
- Sie möchten die Hybridlösung → Docsbook (Git-Quelle, alles andere verwaltet)
Weiterführende Lektüre#
- Die besten Dokumentationsplattformen für Start-ups im Jahr 2026
- Docusaurus vs. Docsbook im Jahr 2026
- Vergleich kostenloser Dokumentationshosting-Anbieter
Docsbook ist die hybride Lösung: Der Quellcode bleibt in Git, während KI, SEO, Übersetzungen und MCP verwaltet werden. Die Preise richten sich nach der KI-Nutzung und werden nicht als Tarif verkauft – aktuelle Zahlen findest du unter docsbook.io/pricing.