Docs as Code: Was es ist und wo es bei Wachstum scheitert

Docs as Code gehört seit mehr als einem Jahrzehnt zur modernen technischen Dokumentation. 2015 sprach Riona MacNamara auf der Write the Docs darüber, wie die Einführung von Docs as Code die Dokumentation bei Google verändert hatte.

Und es ist nachvollziehbar, warum der Ansatz so beliebt wurde.

Wenn Sie ein Engineering-Team leiten, können Sie mit Docs as Code die Dokumentation nah an dem Code halten, den sie beschreibt.

Ihre Engineers arbeiten mit Tools, die sie bereits kennen, und Änderungen an der Dokumentation durchlaufen denselben Pull-Request-Review, dieselben Continuous-Integration-Checks (CI) und denselben Veröffentlichungsprozess wie die Codeänderungen, die sie beschreiben.

Diesem Setup liegen jedoch zwei Annahmen zugrunde: Die Personen, die die Dokumentation pflegen, arbeiten bereits mit Git, und die meisten Änderungen, durch die diese Dokumentation veraltet, passieren in der Nähe des Repositorys.

Wenn das Team wächst, verfügen Produkt und Support über mehr Kontext, Releases betreffen mehr Systeme, und manche Überlegungen hinter dem Code werden nirgendwo festgehalten.

In diesem Artikel sehen wir uns an, was sich ändert, wenn dieses Setup über Ihre Engineers und das Repository hinauswächst, und warum diese Veränderungen für wachsende Teams wichtig sind, die technisches Wissen pflegen.

Das Wichtigste in Kürze

• Docs as Code eignet sich für codenahe Dokumentation, wenn die Personen, die sie pflegen, bereits mit Git arbeiten.
• Ein Git-basierter Workflow liefert Ihnen Commit-Historie, Diffs, Pull-Request-Reviews und CI-Checks für die Änderungen, die Personen an der Dokumentation vornehmen. Er kann jedoch keine unberührte Seite markieren, die ebenfalls hätte geändert werden müssen.
• Sobald Produkt, Support, Technical Writer und andere Teams technischen Kontext beisteuern, bleiben bei einem reinen Git-Beitragsweg immer mehr nützliche Informationen in Slack, Tickets und den Köpfen der Mitarbeitenden.
• Ihr Repository bewahrt das Engineering-Wissen, das dort festgehalten wird. Entscheidungen, Abwägungen, Workarounds und historischer Kontext bleiben implizit, bis jemand sie aufschreibt.
• Sie können Docs as Code für Dokumentation beibehalten, die nah am Code liegen sollte, und dem Rest des Teams zugleich einen gepflegten Ort für Wissen geben, das von anderen Systemen und menschlichem Kontext abhängt.

Was ist Docs as Code?

Docs as Code ist ein Ansatz für technische Dokumentation, bei dem Tools und Workflows aus der Softwareentwicklung genutzt werden, um Dokumentation zu schreiben, zu prüfen, zu versionieren, zu testen und zu veröffentlichen.

Write the Docs, eine weltweite Community von Dokumentationsfachleuten, definiert Docs as Code als die Nutzung derselben Tools und Prozesse, die Entwickler für Software verwenden, darunter Issue-Tracker, Git, Plain-Text-Markup, Code-Reviews und automatisierte Tests.

Ein typisches Docs-as-Code-Setup umfasst:

Ein Beispiel: Ein Engineer, der ein neues Feature dokumentiert, aktualisiert die Markdown-Quelle, committet die Änderung in einen Branch und öffnet einen Pull Request. Reviewer prüfen den Diff zusammen mit der zugehörigen Codeänderung, die CI-Checks laufen, und sobald der Pull Request gemergt ist, kann der Dokumentations-Build die aktualisierte Seite veröffentlichen.

Warum Engineering-Teams Docs as Code nutzen

Engineering-Teams nutzen Docs as Code aus weitgehend demselben Grund, aus dem sie Git für Code nutzen: Die Dokumentation erhält eine versionierte, überprüfbare Änderungshistorie.

Für Engineering-Teams gibt es vier praktische Vorteile:

• Das Feature und seine Dokumentation können im selben Pull Request ausgeliefert werden. Reviewer sehen die Codeänderung und die Aktualisierung der Dokumentation im selben Review-Kontext.
• Jede Änderung an der Dokumentation hat eine Commit-Historie. Diffs, Commits, Autorenschaft und frühere Versionen machen leicht nachvollziehbar, was sich wann geändert hat.
• Release-gebundene Dokumentation kann dem Release folgen. API-Referenzen, Migrationshinweise und Integrationsdokumentation können im selben Rhythmus aktualisiert werden wie der Code, den sie beschreiben.
• CI übernimmt die mechanischen Prüfungen. Linter, Link-Checks, Status-Checks und Dokumentations-Builds erkennen Formatierungs- und Build-Fehler, bevor die Dokumentation veröffentlicht wird.

Über diese praktischen Vorteile hinaus wird von Docs as Code oft erwartet, zwei größere Dokumentationsprobleme zu lösen:

• Aktualität. Wenn die Dokumentation nah am Code liegt, sollten Teams sie eher aktualisieren, wenn sich das Produkt ändert.
• Weniger Informationssilos. Wenn alle Beitragenden einen gemeinsamen Workflow nutzen, sollte technisches Wissen seltener in separaten Tools oder bei einzelnen Personen verschwinden.

Damit eines dieser Versprechen eingelöst wird, muss trotzdem jemand bemerken, welche Dokumentation Aufmerksamkeit braucht, und die Personen mit dem fehlenden Kontext brauchen einen Beitragsweg, den sie auch tatsächlich nutzen. Wie Sie in den folgenden Abschnitten sehen werden, können beide Versprechen scheitern.

Wann Docs as Code der richtige Ansatz ist

Es gibt Fälle, in denen Docs as Code genau das Setup ist, das Sie brauchen:

• Für ein kleines, Engineering-lastiges Team. Alle beobachten bereits dasselbe Repository, sodass die Dokumentation in den Pull-Request-Workflow integriert werden kann, ohne einen weiteren Prozess zu schaffen, den das Team pflegen muss.
• Für API- und Referenzdokumentation. Wenn sich ein Endpoint, ein Parameter oder ein SDK ändert, muss sich die Referenz oft mit ändern. Dieselben Reviewer verstehen in der Regel beide Seiten der Änderung.
• Für release-gebundene technische Dokumentation. Migrationshinweise, Integrationsdokumentation und ähnliche Inhalte profitieren davon, Versionierung und Review-Zyklus mit dem Release zu teilen.

Tom Johnson, API Technical Writer bei Google und zuvor bei Amazon tätig, bevorzugt Docs as Code insgesamt nach wie vor, räumt aber offen ein, dass Git für Beitragende mit unterschiedlichem technischem Kenntnisstand Reibung erzeugt.

In einem Beitrag von 2024 argumentiert er, dass Git für Teams von Technical Writern mit unterschiedlichem technischem Hintergrund schwierig werden kann, selbst wenn der Rest des Docs-as-Code-Workflows weiterhin gut funktioniert.

Sein Punkt leuchtet ein: Docs as Code kann weiterhin wertvoll sein, während Git für einige der Personen, die die Dokumentation pflegen sollen, zur Hürde wird.

Stellen Sie sich also zwei Fragen:

• Wer pflegt diese Dokumentation tatsächlich?
• Wo passieren die Änderungen, durch die sie veraltet?

Wenn beide Antworten weiterhin auf Engineers und das Repository verweisen, leistet Docs as Code genau das, was Sie brauchen. Sobald die Antworten aber Support, Produkt, Slack, Linear, Jira, Kundengespräche und Personen außerhalb des Engineerings nennen, haben Sie ein Problem: Ihr Dokumentationssystem ist über das Repository hinausgewachsen.

Warum Docs as Code für wachsende Teams an Grenzen stößt

Es gibt keine bestimmte Teamgröße, ab der ein Team Docs as Code entwächst. Was sich irgendwann ändert, ist die Arbeitslast rund um das Repository: Mehr Personen müssen beitragen, mehr Systeme können beeinflussen, was in der Dokumentation stehen sollte, und mehr Engineering-Wissen entsteht außerhalb von Git.

So sieht die Entwicklung bis zu diesem Punkt aus:

Wenn Sie Phase vier erreicht haben, bedeutet es längst mehr als Markdown-Updates bei Codeänderungen, die Dokumentation aktuell zu halten. Jetzt muss jemand Änderungen in mehreren Systemen mit der richtigen Dokumentation verknüpfen und Kontext von Personen einholen, die das Repository vielleicht nie öffnen.

Versionskontrolle hält Dokumentation nicht aktuell

Git kann alles richtig machen, während die Dokumentation falsch ist.

Bei einem Feature-Release zum Beispiel aktualisiert der Engineer den Code, die Tests laufen durch, CI bleibt grün, der Pull Request wird gemergt und der Dokumentations-Build ist erfolgreich.

Das Release ändert aber auch einen bestehenden Einrichtungsschritt, der in einer älteren Markdown-Quelldatei beschrieben ist, und niemand fasst diese Datei an.

Die Pipeline ist grün, während die Dokumentation bereits veraltet ist.

Git hat genau das getan, was es tun sollte. Es hat die Commits und Diffs für die Dateien erfasst, die geändert wurden. Es konnte Ihnen aber nicht sagen, welche unberührte Dokumentation ebenfalls hätte geändert werden müssen.

Dasselbe hören wir von Teams, die Dokumentation über mehrere GitHub-Repositorys hinweg pflegen. Ein Team, mit dem wir gesprochen haben, sagte, dass seine Dokumentation dem Release-Rhythmus ständig hinterherhinkte:

Und wenn Sie sich die Zeitstempel der letzten Änderung ansehen, wird es noch trügerischer. Eine Seite kann am Montag bearbeitet werden, eine Produktänderung am Dienstag ausgeliefert werden, und am Mittwoch prangt ein aktueller Zeitstempel über veralteter Dokumentation.

An diesem Punkt veraltet Ihr Wissen mitten in einem gut geführten Docs-as-Code-Workflow. Die veraltete Seite sieht für alle weiterhin normal aus, was es leider noch leichter macht, sie zu übersehen.

Wenn eine Kollegin oder ein Kollege irgendwann auf eine falsche Antwort stößt, fragen sie sich, was sonst noch veraltet sein könnte. Wiederholt sich das ein paar Mal, fragen Teammitglieder lieber den Engineer, der „wirklich Bescheid weiß“, weil sie der Dokumentation nicht mehr als verlässlicher Single Source of Truth vertrauen.

Git-basierte Beiträge können Informationssilos verstärken

Git-basierte Beiträge funktionieren reibungslos, wenn die Personen mit dem Wissen ohnehin in Git arbeiten. Sobald nützlicher Kontext bei Produkt, Support, Operations oder anderen Teams liegt, kann der Beitragsworkflow selbst der Grund dafür werden, dass diese Informationen nie in der Dokumentation ankommen.

Für einen Engineer sind das Öffnen eines Pull Requests, die Arbeit in Markdown und das Einhalten von Repository-Konventionen Alltag. Für jemanden in Support, Produkt oder Operations kann die Korrektur eines einzigen falschen Satzes bedeuten, sich mit Branches, Berechtigungen, Markdown-Konventionen und Code-Reviews auseinanderzusetzen, bevor die Korrektur in der Dokumentation ankommt.

Johnson hat das bei Amazon erlebt. Ihm zufolge verschärfte ein Team seinen Git-Branching-Workflow, nachdem unveröffentlichte Inhalte in einen Produktions-Branch gemergt worden waren, und der Prozess wurde so komplex, dass ein neuer Technical Writer Angst hatte, auch nur eine kleine Änderung vorzunehmen.

Johnson sagt dazu:

Er sagt nach wie vor, dass er Docs as Code insgesamt bevorzugt. Der Workflow hat echte Vorteile. Die Reibung entsteht dadurch, dass alle, die nützlichen Kontext haben, einen Engineering-Workflow übernehmen sollen, nur um die Dokumentation zu korrigieren.

Ähnliche Bedenken haben wir in Gesprächen mit Engineering-Teams gehört. In einem Unternehmen fanden nicht technische Beitragende es schwierig, Inhalte in GitHub zu aktualisieren, also veraltete die Dokumentation, und Fragen landeten standardmäßig in Slack.

Stellen Sie sich vor, eine Support-Mitarbeiterin entdeckt einen falschen Einrichtungsschritt, während sie einem Kunden hilft.

Die Seite zu korrigieren bedeutet, einen Pull Request zu durchlaufen; in Slack „Hey, dieser Schritt hat sich geändert“ zu schreiben, dauert zehn Sekunden. Die Nachricht gewinnt.

Die Korrektur existiert, kommt aber nie in der Dokumentation an. Am Ende haben Sie ein gemeinsames Repository, während nützlicher Kontext über Slack, Tickets und die Personen verstreut bleibt, die die Antwort kennen.

Das Repository enthält nicht alles, was Ihre Engineers wissen

Selbst wenn alle Beitragenden sicher mit Git umgehen, enthält das Repository nur das, was tatsächlich festgehalten wurde.

Der Code liefert Ihnen die Implementierung. READMEs, Architecture Decision Records (ADRs) und andere Dokumentation im Repository liefern zusätzliche Erklärungen. Ein großer Teil des Engineering-Kontexts steckt aber in den Überlegungen hinter der Arbeit:

• Architekturentscheidungen: warum sich das Team für diesen Ansatz entschieden hat und worauf er optimiert war.
• Abwägungen: welche Alternativen in Betracht gezogen wurden und warum sie verworfen wurden.
• Workarounds: die praktischen Kniffe, die erfahrene Engineers anwenden, wenn der dokumentierte Weg nicht ausreicht.
• Historischer Kontext: alte Entscheidungen, die erklären, warum ein ungewöhnlicher Teil des Systems noch existiert.
• Kontext aus Incidents und von Kunden: Erkenntnisse aus Supportfällen, Incidents und internen Gesprächen, die den Umgang mit dem System verändert haben.

Ein Teil dieses Kontexts landet in einem ADR, einem Ticket oder einer README. Vieles davon bleibt als Stammeswissen in Slack-Threads, Meetings und den Köpfen einzelner Engineers.

Ein Team, mit dem wir gesprochen haben, schätzte, dass rund 80 % seines operativen Wissens noch implizit war und nur in den Köpfen der Mitarbeitenden existierte.

Ein wachsendes Team erledigt also zwei Aufgaben parallel:

1. Das bereits dokumentierte Wissen korrekt halten, während sich das Produkt verändert.
2. Die Entscheidungen, Workarounds und den Kontext erfassen, die es nie ins Repository geschafft haben.

Sobald Sie beides bewältigen müssen, reicht Git nicht mehr aus. Sie brauchen zusätzlich eine Ebene, die Änderungen in den Tools Ihres Teams beobachtet und den Mitarbeitenden einen Ort bietet, um Kontext festzuhalten, der sonst außerhalb von Git bliebe.

Ermöglichen Sie allen, zur Dokumentation beizutragen

Mit Slite können Personen im gesamten Unternehmen zur Dokumentation beitragen, ohne denselben Git-Workflow durchlaufen zu müssen.

• Jemand aus Support oder Produkt kann das Dokument öffnen und Änderungen direkt im WYSIWYG-Editor vornehmen.
• Entwickler können in ihrem bevorzugten KI-Tool oder Harness bleiben, etwa Claude, ChatGPT oder Cursor, und über Slites MCP beitragen. Der MCP umfasst auch Tool-Calls für Kommentare, sodass sie Diskussionen starten, lesen, beantworten und abschließen können, ohne diese Umgebung zu verlassen.
• Teams können außerdem die API von Slite nutzen, um Dokumentation programmatisch zu erstellen und zu aktualisieren.

Plaid zum Beispiel hatte fast 3.000 interne Markdown-Dokumente in Git, als das Unternehmen beschloss, sein internes Dokumentationssystem neu aufzubauen.

Eines der Ziele war, den GitHub-Pull-Request-Workflow für Änderungen an der Dokumentation durch WYSIWYG-Bearbeitung zu ersetzen.

Nach der Evaluierung von drei Plattformen entschied sich Plaid für Slite, und alle Pilotnutzer bevorzugten es, unter anderem wegen der intuitiven WYSIWYG-Bearbeitung.

Sechs Monate nach der Migration war die Zahl der monatlich aktiven Dokumentationsautoren um 63 % gestiegen, von 65 auf 107.

Wachsende Teams brauchen eine sich selbst pflegende Wissensebene über dem Repository

Sobald Ihre Dokumentation von Codeänderungen, Tickets, Supportgesprächen und Personen im gesamten Unternehmen abhängt, brauchen Sie mehr als Git.

Sie brauchen ein System, das bemerkt, wenn sich die Realität ändert, diese Änderungen mit der richtigen Dokumentation verknüpft und den Menschen die Kontrolle über vertrauenswürdiges Wissen lässt.

So funktioniert es:

1. Geben Sie Beitragenden einen gemeinsamen Arbeitsort

Mit dem WYSIWYG-Editor von Slite erhalten Engineers, Produkt, Support, Technical Writer und andere Fachexperten einen gemeinsamen Ort, um Erklärungen, Entscheidungen und Kontext aus ihrer eigenen Arbeit neben der übrigen Dokumentation zu ergänzen.

2. Verbinden Sie die Dokumentation mit den Orten, an denen sich die Arbeit ändert

Engineering-Teams können Quellen wie GitHub, GitLab, Jira und Linear anbinden. Slite Agent kann die Wissensdatenbank mit den Aktivitäten in diesen Tools abgleichen und diese Änderungen als Signale nutzen, dass ein bestehendes Dokument womöglich noch einmal geprüft werden sollte.

3. Machen Sie aus diesen Signalen etwas, worauf das Team reagieren kann

Wenn Slite Agent erkennt, dass ein Dokument wahrscheinlich veraltet ist, kann er die betroffene Dokumentation identifizieren und einen Aktualisierungsvorschlag entwerfen, statt darauf zu warten, dass jemand die veraltete Seite entdeckt und dann korrigiert.

4. Behalten Sie die Kontrolle über die Single Source of Truth

Jeder Aktualisierungsvorschlag geht zur menschlichen Prüfung in Triage, sodass jemand, der den Kontext versteht, die Änderung annehmen, überarbeiten oder verwerfen kann, bevor sie Teil der Single Source of Truth wird.

Ihr Git-basierter Dokumentations-Workflow kann für Dokumentation, die ins Repository gehört, bestehen bleiben. Slite setzt als sich selbst pflegende Wissensebene auf diesem Workflow auf, für Informationen, die von Änderungen in anderen Systemen und vom Kontext von Personen im gesamten Unternehmen abhängen.

Im Kern kann Docs as Code also Teil Ihres Dokumentationssystems bleiben. Es muss nur nicht das gesamte System sein.

Wenn Sie sehen möchten, wie Slite technisches Wissen mit den Engineering-Tools verbunden hält, die Ihr Team bereits nutzt, buchen Sie eine Demo für eine Führung durch das Produkt.

FAQ

Was sind Best Practices für Docs as Code?

Halten Sie codenahe Dokumentation nah am Code, aktualisieren Sie direkt betroffene Dokumentation im selben Pull Request, automatisieren Sie sinnvolle Prüfungen und legen Sie klare Verantwortliche fest. Wenn wichtige Änderungen außerhalb des Repositorys passieren, stellen Sie sicher, dass Ihr Pflegeprozess auch diese erfasst.

Was sind Beispiele für Docs as Code?

Gängige Beispiele sind API-Dokumentation, Entwicklerleitfäden, Integrationsdokumentation, Migrationshinweise und technisches Referenzmaterial, die in Markdown oder einem anderen Klartextformat geschrieben und über Git verwaltet werden.

Welche Tools werden für Docs as Code verwendet?

Zu den gängigen Tools gehören GitHub, GitLab oder Bitbucket für das Repository-Hosting und Pull-Request-Reviews, Markdown oder AsciiDoc für die Erstellung, Vale oder markdownlint für CI-Checks sowie Docusaurus, MkDocs oder Sphinx für Static-Site-Builds. Slite kann diesen Stack als gepflegte Wissensebene für interne Dokumentation ergänzen, die von Änderungen und Kontext außerhalb von Git abhängt.

Welche Rolle spielt KI bei Docs as Code?

KI kann helfen, Dokumentation zu entwerfen, wahrscheinlich veraltete Seiten zu erkennen und sie zur Prüfung zu markieren, nachdem sich das zugrunde liegende Produkt geändert hat. Eine menschliche Prüfung bleibt wichtig, bevor von KI vorgeschlagene Aktualisierungen zu vertrauenswürdiger Dokumentation werden.

Ist Docs like Code dasselbe wie Docs as Code?

Ja. „Docs like Code“ und „Docs as Code“ bezeichnen im Allgemeinen denselben Ansatz: Dokumentation mit Git, Plain-Text-Markup, Peer-Reviews, automatisierten Prüfungen und Continuous Integration zu verwalten.