Dokumentation im KI-Projekt: Backbone für nachhaltigen Erfolg
Technisch sauber, aber ohne nachvollziehbare Spur? Wer als IT-Leiter oder Architekt Cloud-Projekte mit Fokus KI verantwortet, weiß: Die besten Lösungen nützen wenig, wenn ihre Entstehung, Betriebslogik oder Automatisierungsschritte nicht dokumentiert sind. Denn gerade in hochdynamischen Umgebungen wie AWS, Azure oder GCP ist Dokumentation kein Zusatz, sondern kritischer Bestandteil – wenn auch eine oft unsichtbare.
Dokumentation im Cloud-Zeitalter: Mehr als ein Wiki-Eintrag
Ein Beispiel aus der PROTOS-Praxis zeigt, wie essenziell durchdachte Dokumentation heute ist: In einem aktuellen Kundenprojekt haben wir ein System zur automatisierten Ticketanalyse mit generativer KI in der AWS-Cloud entwickelt. Neben der Entwicklung einer skalierbaren Architektur, der Umsetzung von API-Integrationen und dem Aufbau eines effizienten ML-Modells war von Beginn an klar, dass jede Entscheidung, Konfiguration und Automatisierung nachvollziehbar dokumentiert sein muss.
Diese Anforderung hatte mehrere Gründe: Zum einen war die Dokumentation notwendig, um die unternehmensinternen Security- und Compliance-Vorgaben im Rahmen eines KI-Acts zu erfüllen. Zum anderen waren an dem Projekt verschiedene Teams beteiligt – von DevOps bis zum KI-Team – und Entscheidungen etwa zu Skalierungsoptionen, IAM-Rollen oder Data-Pipelines mussten auch im Nachhinein transparent und prüfbar sein. Zusätzlich brachte die Integration in ein bestehendes Support-System wie Jira Anforderungen an die Compliance-Dokumentation und erforderte spezifische Security-Freigaben. Nicht zuletzt sollte der Betrieb und die Weiterentwicklung langfristig an ein internes IT-Team übergeben werden können. Ohne eine lückenlose Dokumentation wäre das gesamte Vorhaben riskant, ineffizient und im Regelbetrieb kaum tragbar gewesen.
„Wenn wir heute nachvollziehbar dokumentieren, warum ein bestimmter Modellparameter gewählt wurde oder wie ein API-Fallback greift, dann ermöglichen wir morgen einen reibungslosen Wissenstransfer, sichere Weiterentwicklungen und verlässliche Audits.
Ohne diese Transparenz wäre ein dauerhaft sicherer Betrieb nicht verantwortbar – und jede Weiterentwicklung ein Blindflug.“
Tobias Schulz-Hess, Senior IT-Cloud Architect & zertifizierter Trainer bei PROTOS
Typische Herausforderungen – und wie wir sie bei PROTOS adressieren
Dokumentation als Produkt statt nachgelagerter Pflicht
Im Ticketanalyse-Projekt war von Anfang an klar: Die Dokumentation sollte nicht erst am Ende erstellt werden, sondern parallel zur Implementierung entstehen.
Dazu haben wir in Confluence standardisierte Templates genutzt, beispielsweise für Architekturentscheidungen, IAM-Policies und Data-Flows. Außerdem wurde eine strukturierte Erinnerungsroutine eingeführt, die monatlich Hinweise auf notwendige Aktualisierungen gab. Auch unsere Meetingstruktur haben wir angepasst: Sobald in einem Termin eine Entscheidung getroffen wurde, wurde diese unmittelbar mit einem entsprechenden Dokumentationshinweis verknüpft.
Das Ergebnis war ein fließender Prozess – niemand im Team musste sich nachträglich „extra Zeit freischaufeln“, um Dinge zu dokumentieren. Die Dokumentation war nahtlos in den Arbeitsalltag integriert.
Technische Tiefe ohne Unübersichtlichkeit
Gerade bei Cloud-Projekten kommt es auf Details an:
Warum haben wir welchen Dienst verwendet – und uns gegen andere entschieden?
Welche Lambda-Funktion ruft welches Model-Endpoint auf?
Wie ist das Fallback bei API-Fehlern gelöst?
Wer darf welches Bucket lesen?
Solche Informationen haben wir:
- In architekturspezifischen Mikroseiten abgelegt (eine Seite = ein Architekturentscheidung gemäß dem Konzept der Architecture Decision Records ADR).
- Mit automatisierten Quellcode-Referenzen kombiniert (z. B. via Sphinx-Doku bei Python-Modulen).
- Ergänzt durch grafische BPMN-Modelle (z. B. Camunda zur Beschreibung der Abläufe in der Analyse-Pipeline).
Verantwortung & Aktualität
Technische Dokumentation altert schnell. Deshalb haben wir klare Verantwortlichkeiten festgelegt:
- Pro Service gibt es einen „Doku-Verantwortlichen“ (nicht: Autor), der monatlich prüft, ob Inhalte veraltet sind.
- Änderungen in der CI/CD-Pipeline oder an Modellparametern triggern automatisch eine Doku-Checkliste, die ins Confluence-Board übernommen wird.
- Durch das Zusammenspiel von Jira, Git und Confluence konnten wir sicherstellen, dass Doku und Code nie zu weit auseinanderdriften.
Welche Tools sich in der Praxis bewähren
Technische Teams dokumentieren anders als klassische Projektleiter – und sie brauchen andere Werkzeuge:
- Markdown & Git für die Dokumentation nahe am Quellcode.
- Jira & Confluence für durchgängige Traceability zwischen Tickets, Architekturbeschlüssen und Betriebsdetails.
- Camunda (BPMN) zur Modellierung und Kontrolle von Prozessschritten (z. B. in ML-Pipelines).
- PlantUML oder C4-Diagramme direkt in Markdown-Dateien für In-Repo-Doku.
- Sphinx oder MkDocs für techniknahe Python- oder API-Dokumentation, CI/CD-inklusiv.
- Miro & draw.io für visuelle Architekturübersichten, eingebettet in Projektspaces.
Fazit: Dokumentation ist Betriebssicherheit
In Cloud-Umgebungen mit dynamischen Infrastrukturen, integrierter KI und Microservices ist Dokumentation weit mehr als nur eine gute Praxis – sie ist ein entscheidender Sicherheitsfaktor. Sie sorgt für Transparenz und macht Systeme auditierbar, ermöglicht reibungslose Übergaben zwischen Abteilungen und externen Dienstleistern, reduziert Fehlerquoten und verkürzt Einarbeitungszeiten. Gleichzeitig unterstützt sie die Skalierbarkeit und Wiederverwendbarkeit von Lösungen.
Für unsere Kunden heißt das: Eine durchdachte Dokumentation ist kein Nice-to-have, sondern das operative Rückgrat und ein zentrales Strategieelement. Wer sie konsequent verankert, schafft die Grundlage für mehr Stabilität, höhere Umsetzungsgeschwindigkeit und nachhaltiges Vertrauen.
