SeventyFour | shutterstock.com

DevOps-Teams und technische Dokumentationen verbindet eine über Jahre aufgebaute Hassliebe. Entwickler verabscheuen es geradezu, undokumentierten Code lesen und warten zu müssen. Architektur-Diagramme taugen zwar unter Umständen für gutes Storytelling, sind aber verglichen mit der tatsächlich implementierten Infrastruktur meist eher Fiktion. Selbst ITSM-Prozesse für Incidents, Requests und Change Management laufen in den seltensten Fällen so ab, wie es die Dokumentation vorsieht.

CIOs, CTOs und andere Führungskräfte bestehen selbstverständlich auf technische Dokumentation. Allerdings sind in den Projektbudgets meist keine technischen Redakteure vorgesehen. Die meisten agilen Entwicklungsteams kommen deshalb schon rein zeitmäßig nicht über die absoluten Grundlagen wie einer Dokumentation auf Code-Ebene oder in Form von README-Dateien hinaus. Die Folge: Die technischen Dokumentationen, die maßgeblich sind für die Business-Regeln einer Applikation, die Journey Maps, die Architektur, die APIs und die Standard-Prozesse, sind regelmäßig unvollständig und veraltet. Das muss allerdings nicht so laufen – denn auch in diesem Bereich kann generative künstliche Intelligenz (Generative AI, GenAI) unterstützen.

Dokumentation sucht Zielgruppenansprache

Die wichtigste Voraussetzung dafür ist es, genau zu wissen, wen die technische Dokumentation adressieren soll – und wie diese Zielgruppe das Material nutzen soll. Folgende Zielgruppen sollten DevOps-Teams dabei berücksichtigen:

• Neu an Bord gekommene Entwickler suchen eine Dokumentation, die die Architektur, nicht verhandelbare DevOps-Methoden, den Softwareentwicklungsprozess sowie High-Level-Codestrukturen abdeckt. Nur so können sie schnell produktiv werden und Lösungen entwickeln, die den Standards entsprechen.
• Externe Development-Teams erwarten API-Dokumentationen, README-Dateien in Git-Repositories, Datenkataloge inklusive Datendefinitionen sowie Leitfäden zu Protokolldateien und anderen Observability-Artefakten.
• Softwarearchitekten, Sicherheitsprofis und Site Reliability Engineers (SREs) brauchen eine Dokumentation, um Vorschläge zu App-Modernisierungen zu liefern, Programme aufzusetzen, um technische Schulden zu adressieren sowie, um Incident Response und Ursachenanalysen zu unterstützen.
• Datenwissenschaftler, Governance-Spezialisten und Software Engineers, die mit Daten-Pipelines arbeiten, nutzen oft Daten, die über APIs und Applikationen bereitgestellt werden, für Reportings, Datenvisualisierungen und -Analysen, sowie für KI-Modelle. Sie haben vor allem Interesse an einem aktualisierten Datenkatalog und wollen die Data Lineage verstehen, um sie für datengetriebenes Decision Making zu nutzen.
• Produkt-Manager und -Owner sowie Change Manager und andere Fachleute wollen wissen, “wie das System funktioniert”. Sie haben zwar kein Interesse, sich mit Code zu befassen, brauchen aber mehr Details als die Release Notes typischerweise bieten.
• Auditoren und Compliance-Experten wollen die entsprechenden Dokumentationen für die Erfüllung von Standards wie ISO 27001, ISO 9001 oder SOC 2 einsehen.
• KI-Code-Assistenten und -Agenten konsumieren technische Dokumentationen, um ihre Relevanz und Genauigkeit zu optimieren.

Technische Dokumentationen mit GenAI: 5 Use Cases

Beim Blick auf die konkrete Umsetzung dreht sich alles um die Frage, wie sich KI-Tools einsetzen lassen, um diese höchst unterschiedlichen Zielgruppenanforderungen zielgerichtet abzubilden. Die Antwort liefern die folgenden fünf Anwendungsfälle.  

1. Features dokumentieren

“Die Dokumentationen der Google Cloud APIs sind in Code geschrieben. Der einzige Weg, diese Abertausenden von API-Dokumentationen aktuell zu halten, führt über Automatisierung”, hält Miles Ward, CTO beim Cloud-Spezialisten SADA, fest. Er fügt hinzu: “Wir haben NotebookLM mit unseren technischen Dokumentationen gefüttert. Jetzt lasse ich mich von einem KI-generierten Podcast in natürlicher Sprache über die Nuancen unserer Feature-Interaktionen aufklären.”

Laut dem Technologieentscheider entwickle sich der State of the Art in diesem Bereich rasant weiter. Neben NotebookLM könnten auch Tools wie Gemini oder Mariner dabei unterstützen, Dokumentationen vom Mühsal zum Asset zu transformieren, so Ward.

Um zu dokumentieren, wie Features funktionieren, sollten Sie folgende Aspekte berücksichtigen (respektive aktuell halten):

• Eine Feature-Spezifikation, die die Anforderungen (inklusive Endbenutzer-Dokumentation) abbildet;
• Ein prägnantes, technisches Design, das Architektur, Abhängigkeiten, Testing, Security, Konfiguration und Deployment umfasst;
• Referenzen, inklusive Links zu agilen User Strories und ITSM-Tickets.   

Zu den gängigen Tools für Dokumentationen auf Funktionsebene gehören zum Beispiel:

• Microsoft Teams,
• Atlassian Confluence,
• Google Workspace,
• Notion, und
• MediaWiki.

2. APIs, Data Dictionaries und Pipelines dokumentieren

Laut Armando Franco, beim Serviceanbieter TEKsystems für technologische Modernisierungen verantwortlich, ist dank generativer KI bereits ein bedeutender Wandel in Sachen Dokumentation zu beobachten: “Sie wird immer mehr vom nachträglichen Gedanken zu einem natürlichen Nebenprodukt des Entwicklungsprozesses selbst. Während die Teams Microservices entwickeln, kann die Technologie zum Beispiel automatisiert OpenAPI-Spezifikationen produzieren und instandhalten, die die Endpoints, Payloads und Authentifizierungsmethoden akkurat abbilden. Und für Daten-Teams kann die KI Lineage-Diagramme und Datenkataloge direkt aus SQL-Code oder ETL-Pipelines generieren, was umgebungsübergreifende Konsistenz sicherstellt”, erklärt der Manager.

DevOps-Teams sollten dabei im Hinterkopf behalten, dass sie nicht zur Zielgruppe einer technischen Dokumentation gehören. Interne oder externe Entwickler sind die primären Adressaten. Folgende Tools empfehlen sich für die unterschiedlichen, technischen Dokumentationen:

• Data Dictionaries werden idealerweise in Datenkatalogen dokumentiert. Etwa Alation, Atlan, Ataccama, AWS Glue Data Catalog, Azure Data Catalog, Collibra, Data.world, Erwin Data Catalog, Google Dataplex Universal Catalog, Informatica Enterprise Data Catalog oder Secoda. 
• DataOps-Teams, die Daten-Pipelines und Integrationsplattformen einsetzen, können auf Visual Design Tools zurückgreifen, um Datenflüsse sichtbar zu machen und Lineage-Diagramme zu erstellen.
• Um APIs zu dokumentieren, empfehlen sich Tools wie Postman, Redocly, Swagger oder Stoplight.

3. Laufzeit und Standardprozesse dokumentieren

Wie Kevin Cochrane, CMO beim alternativen Cloud-Anbieter Vultr, festhält, können traditionelle Dokumentationspraktiken nicht mit der dynamischen Natur heutiger KI-getriebener Cloud-Systeme Schritt halten. “CTOs nutzen inzwischen GenAI-Tools, um Protokolle, Konfigurationen und Laufzeitdaten in ‚lebendige‘ Dokumentationen zu verwandeln, die sich mit den Systemen weiterentwickeln.”

Laut Cochrane reduziere das einerseits Reibungspunkte und andererseits die Entwicklungszeiten: “Dieser Ansatz macht die Dokumentation zu einem Continuity-Tool, das gemeinsamen Kontext vorhält, Single Points of Failure reduziert und Execution Breakdowns über den gesamten Stack hinweg verhindert.”

DevOps Best Practices fokussieren Workflows, Tools und Konfigurationen. Wie die Teams die Übergänge von der Entwicklung zu operativen Funktionen dokumentieren, bleibt ihnen selbst überlassen. Folgende Tool-Kategorien können dabei unterstützen:

• Tools, um operative Knowledge-Basen und Standardprozesse zu erstellen – etwa Atlassian Jira Service Manager, Freshservice Knowledge Base, ServiceNow Knowledge Management oder Zendesk Guide.
• KI-basierte Tools, um Protokolle zu analyieren – etwa Datadog, Dynatrace, LogicMonitor, Logz.io, New Relic, Splunk oder Sumo Logic.
• Tools, um Public-Cloud-Infrastrukturen zu visualieren – etwa Cloudcraft, Hava oder Lucidscale.
• Tools, um Architekturen, Sequenzen und andere “Flows” zu visualisieren – etwa Draw.io, Figma, Eraser, Lucidchart, Miro oder Visio.

4. Dokumentationen für KI-Agenten

Diverse KI-Agenten können inzwischen nicht mehr nur Codebasen analysieren, sondern auch Softwaredokumentationen, um ihren Kontext anzureichern. Andrew Filev, CEO und Gründer des Agentic-AI-Anbieters Zencoder, erklärt: “Werden sämtliche Änderungen am Code dokumentiert, können KI-Agenten nicht nur verstehen, was der Code bewirkt, sondern auch, warum er auf eine bestimmte Art und Weise geschrieben wurde. Dieser historische Kontext transformiert KI vom Coding-Assistenten zu einem vollwertigen Teammitglied.”

Das institutionalisierte Wissen, das zuvor in den Köpfen der Entwickler oder einzelnen Slack-Threads isoliert vorgelegen habe, werde damit zur durchsuchbaren Intelligenz, die jede nachfolgende KI-Interaktion optimiere, so Filev. Der Manager fügt hinzu: “Teams, die diesen Ansatz nutzen, berichten davon, dass ihre KI-Agenten nach rund sechs Monaten dramatisch an Effektivität zulegen, wenn es darum geht, spezifische Muster in Codebasen und Konventionen zu verstehen.”

DevOps-Teams sollten deshalb erwägen, ihre KI-Coding-Tools mit folgenden Informationen zu füttern:  

• API-Dokumentationen,
• User Stories, inklusive Akzeptanzkriterien,
• Coding Standards,
• Architekturprinzipien,
• README-Dateien,
• Secure Coding Guidelines,
• Datenschutzvorgaben und
• Compliance-Referenzen.

5. Legacy-Applikationen dokumentieren

Ein weiterer Anwendungsfall besteht darin, undokumentierte Anwendungen anzugehen – insbesondere, wenn die ursprünglichen Entwickler nicht mehr an Bord des Unternehmens, beziehungsweise der Organisation sind. Laut Sanjay Gidwani, COO beim DevOPs-Anbieter Copado, kann künstliche Intelligenz in dreifacher Hinsicht dabei unterstützen, diese Aufgabe zu bewältigen. Demnach:

• könne GenAI gut große Informationsmengen zusammenfassen – habe also entsprechend auch keine Probleme damit, existierenden Quellcode zu lesen und die dahinterstehende Absicht zusammenzufassen.
• verließen sich viele Business-Applikationen auf Konfigurations-Metadaten. Diese könnten entsprechend fähige KI-Tools lesen und dokumentieren.
• eigne sich KI auch, um Daten auf eingesetzte Prozesse hin zu analysieren – inklusive der jeweiligen Zeiträume und beteiligten Personen.  

Vergessen Sie dabei nicht: Auch wenn undokumentierte Systeme problematisch sind (und möglicherweise ein Compliance-Risiko darstellen), ziehen unnötig ausufernde Dokumentationen weitere Herausforderungen nach sich: Diese sind für Menschen schwer zu konsumieren und es ist enorm teuer, sie aktuell zu halten – selbst mit KI-Unterstützung. (fm)

Sie wollen weitere interessante Beiträge zu diversen Themen aus der IT-Welt lesen? Unsere kostenlosen Newsletter liefern Ihnen alles, was IT-Profis wissen sollten – direkt in Ihre Inbox!