Katalog
concept#Software‑Entwicklung#DevOps#Integration#Plattform

Documentation-as-Code

Dokumentation als Code integriert technische Dokumentation in den Softwareentwicklungsprozess: textbasierte Inhalte unter Versionskontrolle, automatisierte Builds und Review‑Workflows.

Documentation-as-Code behandelt die Erstellung und Pflege technischer Dokumentation als Teil des Softwareentwicklungs‑Workflows: Inhalte in Textdateien unter Versionskontrolle, automatisierte Builds, Reviews und Continuous‑Delivery von Docs.
Etabliert
Mittel

Klassifikation

  • Mittel
  • Technisch
  • Architektur
  • Fortgeschritten

Technischer Kontext

CI/CD‑Systeme (GitHub Actions, GitLab CI, Jenkins)Hosting für statische Seiten (ReadTheDocs, Netlify)API‑Generatoren (Swagger/OpenAPI‑Tools)

Prinzipien & Ziele

Dokumentation ist Code: versioniert, reviewbar und automatisierbar.Automatisiere Build und Qualitätssicherung der Dokumentation.Quellen nah am Code halten, Single‑source‑of‑truth bewahren.
Umsetzung
Unternehmen, Domäne, Team

Use Cases & Szenarien

Kompromisse

  • Unvollständige oder veraltete Inhalte, wenn Tests fehlen.
  • Overhead für kleine Dokumentationsanforderungen.
  • Zu enge Kopplung an spezifisches Tooling kann Migration erschweren.
  • Dokumentation nahe am Code pflegen und versionieren.
  • Automatisches Link‑Checking und Linting im CI einführen.
  • Templates und Snippets für Konsistenz bereitstellen.

I/O & Ressourcen

  • Quelltext, API‑Specs oder Markdown/AsciiDoc‑Dateien
  • Build‑Konfigurationen und CI‑Skripte
  • Contributing‑Guidelines und Styleguide
  • Statische HTML/ PDF‑Artefakte oder MD‑Paket
  • Versionierte Dokumentationsreleases
  • Maschinenlesbare Spezifikationen (z. B. OpenAPI)

Beschreibung

Documentation-as-Code behandelt die Erstellung und Pflege technischer Dokumentation als Teil des Softwareentwicklungs‑Workflows: Inhalte in Textdateien unter Versionskontrolle, automatisierte Builds, Reviews und Continuous‑Delivery von Docs. Dadurch entstehen reproduzierbare, kollaborative Prozesse, bessere Nachvollziehbarkeit und Integration in CI/CD‑Pipelines für Entwicklerteams. Es unterstützt Tooling wie Sphinx, MkDocs oder AsciiDoc und fördert konsistente, leicht wartbare Dokumentations‑Artefakte.

✔

  • Bessere Nachvollziehbarkeit durch Versionskontrolle und PR‑Workflows.
  • Konsistente Outputs durch automatisierte Builds und Linting.
  • Ermöglicht kollaborative Beiträge von Entwicklern und Autoren.

✖

  • Initialer Einrichtungsaufwand für CI/CD und Tooling.
  • Erfordert disziplinierte Pflege der Quell‑Dateien.
  • Visuelle WYSIWYG‑Editoren sind weniger integriert.

  • Dokumentations‑Coverage

    Anteil der API‑Endpunkte oder Module mit zugehöriger Dokumentation.

  • Time‑to‑Publish

    Zeit von Änderung bis veröffentlichter Dokumentation im produktiven System.

  • Broken‑Link‑Rate

    Anteil fehlerhafter oder toter Links in der veröffentlichten Dokumentation.

Sphinx‑basierte Python‑Bibliothek

Dokumentation als reStructuredText in Repo, CI baut HTML auf ReadTheDocs.

MkDocs für Produktdokumentation

Markdown‑Quellen im Git, automatischer Deploy auf statische Hosting‑Plattform.

OpenAPI‑generierte Referenzdocs

OpenAPI‑Spec im Repo, Generator erzeugt konsistente Referenzseiten im Build.

1

Evaluieren: Format, Generator und Hosting auswählen.

2

Repository‑Struktur anpassen und Templates hinzufügen.

3

CI‑Pipeline bauen: Linting, Build und Deploy automatisieren.

4

Contributing‑Guide und Styleguide veröffentlichen.

⚠️ Technische Schulden & Engpässe

  • Alte, nicht versionierte Wiki‑Inhalte müssen migriert werden.
  • Skripte und Plugins, die nicht gepflegt werden, blockieren Builds.
  • Spezifische Template‑Anpassungen erschweren Upgrade des Generators.
Manual Review‑AufwandTooling‑KompatibilitätContent‑Konsistenz über Repos
  • Nur README aktualisieren, ohne CI‑Build zu integrieren.
  • Komplexe Layoutwünsche direkt in Quelltext ausführen statt Template‑Erweiterung.
  • Tooling erzwingen, obwohl Team kein Git‑Workflow hat.
  • Keine Governance für Authoring‑Standards festlegen.
  • Ignorieren von Build‑Fehlern im CI erlaubt veraltete Publikationen.
  • Verlust von Meta‑Informationen bei reiner Markdown‑Pflege ohne Struktur.
Git und Branching‑WorkflowsGrundkenntnisse in CI/CD und Build‑SkriptenMarkup‑Formate (Markdown, AsciiDoc, reStructuredText)
Versionierbarkeit und NachvollziehbarkeitAutomatisierbarkeit (Build, Linting, Tests)Integrationsfähigkeit mit CI/CD und Deploy
  • • Notwendigkeit von Versionskontrolle (Git)
  • • CI/CD‑Infrastruktur für Builds
  • • Standards für Format und Linting