Von Confluence zu GitLab: Wie ihr eure Dokumentation zur Grundlage interner AI-Use-Cases macht

Viele Softwareteams stehen gerade vor derselben Frage: Bleibt unsere Dokumentation in Confluence oder bringen wir sie als Markdown-Dateien nach GitLab und machen sie fit für AI, Versionierung und Knowledge-Base-Ingestion?

Genau darüber hatten wir heute ein spannendes Gespräch. Die Idee: bestehende Confluence-Dokumentation mit einem Markdown-Exporter in Dateien überführen, diese in GitLab versionieren und im nächsten Schritt über S3 für eine AWS-Bedrock-Knowledge-Base bereitstellen.

Auf dem Papier klingt das nach einem sehr starken Setup. In der Praxis ist es das oft auch. Aber eben nicht automatisch.

Warum Teams ihre Confluence-Dokumentation nach Markdown migrieren

Der Reiz hinter dem Ansatz ist nachvollziehbar. Confluence ist für kollaboratives Schreiben bequem. Für langlebige technische Dokumentation, saubere Änderungsverfolgung und AI-Readiness ist es aber oft nicht ideal. Git-basierte Markdown-Dokumentation bringt hier mehrere Vorteile mit.

1. Versionierung wird endlich ernst genommen

In GitLab ist Dokumentation nicht mehr bloß irgendwo im Wiki, sondern Teil eines kontrollierten Änderungsprozesses. Änderungen laufen über Merge Requests, sind diffbar, reviewbar und lassen sich direkt Releases, Issues oder Architekturentscheidungen zuordnen.

Gerade bei Architektur-Dokumentation, ADRs, Runbooks oder API-Doku ist das ein echter Vorteil. Denn dort ist nicht nur wichtig, was dokumentiert wurde, sondern auch wann, warum und durch wen etwas geändert wurde.

2. Markdown ist deutlich LLM-freundlicher als Wiki-Chaos

Markdown ist kein Wundermittel. Aber es ist für Large Language Models in der Regel deutlich besser verarbeitbar als inkonsistente, historisch gewachsene Confluence-Seiten mit Rich Text, Makros, Panels und eingebetteten Sonderformaten.

Überschriften, Listen, semantische Abschnitte und klar gegliederte Inhalte helfen später beim Chunking, bei der Retrieval-Qualität und bei der Wiederverwendung in einer Knowledge Base.

3. Die Doku wird AI-ready

Das ist für viele Teams aktuell der eigentliche Treiber. Wer heute technische Dokumentation in GitLab strukturiert ablegt und über S3 bereitstellt, baut nicht nur eine bessere Doku-Ablage. Er schafft ein Fundament für interne AI-Assistenten, RAG-Systeme und semantische Suche.

Ist Confluence zu Markdown in GitLab also die bessere Lösung?

Ja, oft. Aber nicht pauschal. Die Strategie ist gut, wenn ihr sie als Docs-as-Code- und Knowledge-Architecture-Initiative versteht. Sie ist schwach, wenn ihr sie nur als Dateiformat-Wechsel behandelt.

Die technischen Vorteile des Ansatzes

Schauen wir auf die technische Seite.

GitLab als Source of Truth ist ein starkes Modell

Wenn Code, Infrastruktur und technische Dokumentation an einem Ort leben, steigt die Chance, dass Dokumentation tatsächlich aktuell bleibt. Teams können Doku enger an ihre Delivery-Prozesse koppeln. Ownership wird klarer. Reviews werden verbindlicher.

Das ist vor allem dort sinnvoll, wo Dokumentation produktnah ist:

• Architekturentscheidungen (ADRs)
• Runbooks
• Betriebswissen
• API-Dokumentation
• Setup- und Deployment-Anleitungen
• Onboarding für Entwickler

In diesen Bereichen ist Markdown in GitLab oft deutlich robuster als klassisches Wiki-Management.

S3 als Ingestion-Layer ist architektonisch sauber

Der Schritt über S3 ist ebenfalls sinnvoll. Damit trennt ihr die Erstellung und Pflege der Dokumentation von der AI-Ingestion und Bereitstellung. GitLab bleibt die redaktionelle Quelle. S3 dient als sauberer Bereitstellungskanal für Bedrock.

Das ist technisch modular und reduziert Kopplung. Es erlaubt euch auch, später andere Retrieval- oder Search-Systeme anzuschließen, ohne die eigentliche Doku-Grundlage neu bauen zu müssen.

Wo die Strategie in der Praxis scheitern kann

Jetzt zum wichtigeren Teil: den Risiken. Denn genau hier trennt sich gute Idee von funktionierendem System.

1. Export ist nicht gleich verlustfreie Migration

Der größte Denkfehler in solchen Projekten ist zu glauben, dass sich Confluence-Inhalte verlustfrei in Markdown übertragen lassen. Das ist selten der Fall.

Sobald eure Confluence-Doku stark von eingebetteten Makros, Panels, Drawings, Spezialplugins, Tabellenkonstrukten oder komplexen Layouts lebt, müsst ihr mit Informationsverlust rechnen.

Lösung: Migration in Wellen, mit Triage und automatischen Diff-Reports

Statt „alles auf einmal" funktioniert in der Praxis eine dreistufige Triage. Erstens: Inventar erstellen (Confluence-API auslesen, Seiten nach letztem Edit-Datum, Autor, Space, Größe und Makro-Nutzung klassifizieren). Zweitens: drei Buckets bilden – „migrieren wie sie ist", „vor Migration aufräumen", „bewusst nicht migrieren". Drittens: nach jedem Export-Lauf einen automatischen Diff-Report generieren, der pro Seite anzeigt, welche Makros, Embeds oder Tabellen beim Konvertieren verloren gegangen sind. Diese Liste geht direkt als Aufgabe an die Owner – nicht an „das Doku-Team".

2. Bilder, Diagramme und Tabellen bleiben ein Sonderfall

Viele Teams überschätzen textbasierte Doku. In der Realität steckt kritisches Wissen oft in:

• Architekturdiagrammen
• Screenshots
• PDF-Anhängen
• Tabellen
• Draw.io- oder PlantUML-Inhalten

Wenn dieses Wissen nicht sauber textlich beschrieben ist, wird eine reine Markdown-Migration für AI-Zwecke unvollständig bleiben.

Lösung: Diagram-as-Code plus AI-generierte Bildbeschreibungen

Diagramme gehören als Code ins Repo, nicht als binäre Bilder. Konkret heißt das: PlantUML, Mermaid oder Draw.io-XML direkt im Markdown-File einbetten. Damit wird das Diagramm diffbar, reviewbar und vom LLM lesbar. Für bestehende Screenshots und Bilder, die ihr nicht neu zeichnen wollt, lohnt sich ein einmaliger Vision-Pass: ein multimodales Modell erzeugt eine textliche Beschreibung („Das Diagramm zeigt ein Payment-Service mit drei Upstream-Konsumenten und einer SQS-Queue als Buffer"), die als Alt-Text und als nachfolgender Markdown-Absatz unter dem Bild gespeichert wird.

3. Berechtigungen werden schnell zum Risiko

Confluence hat häufig sehr feingranulare Berechtigungen. Ein S3-plus-Bedrock-Setup ist in vielen Fällen gröber. Das ist nicht nur ein technisches Thema, sondern ein Governance-Thema.

Wer Inhalte aus mehreren Spaces oder Teams zentral bereitstellt, muss sehr genau definieren:

• welche Inhalte ingestiert werden
• wer sie abfragen darf
• welche Sensitivitätsstufen es gibt
• ob mehrere Knowledge Bases nötig sind

Lösung: Confidentiality-Level im Front Matter + getrennte S3-Prefixes pro Knowledge Base

Berechtigungen werden vor der Ingestion entschieden, nicht im Frontend. Konkret: Jede Markdown-Datei trägt im Front Matter ein `confidentiality`-Feld (z. B. `public`, `internal`, `restricted`, `secret`). Die CI-Pipeline routet die Dateien anhand dieses Felds in unterschiedliche S3-Prefixes. Pro Sensitivitätsstufe wird eine eigene Bedrock-Knowledge-Base aufgesetzt, mit IAM-Policies, die genau definieren, welche Personengruppe welche KB anfragen darf.

Für die Migration heißt das: Jede aus Confluence exportierte Seite bekommt automatisch das Confidentiality-Level der Quell-Space als Default zugewiesen. Owner können das pro Datei im Merge Request hochstufen, aber niemals heimlich herunterstufen – ein CI-Check verhindert das.

4. Schlechte Struktur bleibt schlechte Struktur

Markdown macht aus schlechter Doku keine gute Doku. Wenn Seiten unklar benannt, nicht gepflegt, ohne Owner oder ohne Lebenszyklus geführt wurden, bleibt das Problem bestehen. Nur eben jetzt in GitLab.

Deshalb ist die eigentliche Frage nicht „Wie exportieren wir Confluence nach Markdown?", sondern „Wie strukturieren wir Wissen so, dass Menschen und LLMs zuverlässig damit arbeiten können?".

Lösung: Doc-Types, Templates und Lifecycle-Status erzwingen

Ohne Schema bleibt Wildwuchs Wildwuchs. Wir definieren vor der Migration eine kleine, harte Liste an Dokumenttypen – etwa `adr`, `runbook`, `api`, `concept`, `onboarding`, `howto`. Pro Doc-Type gibt es ein Template (Pflicht-Überschriften, vorgegebene Front-Matter-Felder, leere Beispiel-Sektionen). Eine GitLab-CI-Pipeline lehnt Merge Requests ab, wenn Pflichtfelder fehlen oder die Überschriften-Struktur nicht zum Doc-Type passt.

Zusätzlich tragen alle Dokumente ein `lifecycle_status` (`active`, `deprecated`, `archived`) und ein `last_reviewed_at`. Ein nightly Job markiert Dokumente, die länger als 6 Monate nicht reviewt wurden, automatisch als „review fällig" – sichtbar als Issue im Owner-Team. Damit wird Pflege zur sichtbaren Aufgabe, nicht zum Nice-to-have.

Die Business-Perspektive: Warum der Ansatz trotzdem strategisch stark ist

Aus Business-Sicht ist der Ansatz oft sogar interessanter als aus technischer Sicht.

Weniger Tool-Lock-in

Wissen in Markdown-Dateien ist portabler als Wissen in einem proprietären Wiki-Format. Das senkt Abhängigkeiten und erhöht langfristig eure Handlungsfähigkeit.

Bessere Governance

Git-basierte Doku zwingt Teams eher zu Ownership, Review und klareren Zuständigkeiten. Das ist nicht immer bequemer, aber häufig deutlich effektiver.

AI-Enabling mit Substanz

Viele Unternehmen sprechen über AI, ohne ihre Wissensbasis dafür vorbereitet zu haben. Genau deshalb scheitern später viele interne AI-Projekte. Wer Dokumentation früh strukturiert, versioniert und mit Metadaten versieht, reduziert später den Aufwand für RAG, semantische Suche und interne Wissensassistenten massiv.

Schnellere Antworten, besseres Onboarding

Wenn die Doku sauber aufgebaut ist, profitieren nicht nur AI-Systeme. Auch Menschen finden Informationen schneller, neue Teammitglieder onboarden effizienter und operative Rückfragen sinken. Das ist am Ende der eigentliche Business Case.

Unsere Bewertung: Pro und Contra im Überblick

Was für die Migration spricht

• saubere Versionierung und nachvollziehbare Änderungen
• Dokumentation wird reviewbar und release-nah
• bessere Grundlage für LLMs und RAG
• geringerer Vendor-Lock-in
• S3 und Bedrock passen architektonisch gut dazu
• Metadaten, strukturierte Ingestion und Wiederverwendbarkeit werden einfacher

Was dagegen spricht

• Confluence-Makros und komplexe Layouts gehen nicht immer sauber mit
• Bilder, Diagramme und eingebettete Inhalte brauchen Sonderbehandlung
• nicht-technische Stakeholder arbeiten oft ungern in Git-zentrierten Prozessen
• ohne Governance migriert ihr Chaos nur in ein neues Medium
• Berechtigungen und Sensitivität müssen neu gedacht werden

Die wichtigsten Improvements für ein wirklich gutes Setup

Wenn ihr diese Strategie ernsthaft umsetzen wollt, würde ich sie nicht eins zu eins so übernehmen, sondern verbessern.

1. Nicht alles in dasselbe Zielsystem migrieren

Nicht jede Confluence-Seite gehört in GitLab. Technische Doku, ADRs, Runbooks und produktnahe Inhalte passen sehr gut in ein Docs-as-Code-Modell. Für stark kollaborative Dokumentation mit kurzer Lebensdauer eignen sich oft andere Werkzeuge besser.

Dazu gehören zum Beispiel:

• Teams Notes für laufende Abstimmungen, Workshops oder Meeting-Dokumentation
• Miro-Boards für kollaborative Konzeptarbeit, frühe Ideen und visuelle Workshops
• Ticket-Systeme oder Projekttools für operative Aufgaben, Statusstände und kurzfristige Projektkommunikation

2. Front Matter und Metadaten standardisieren

Jede Datei sollte strukturierte Metadaten tragen. So verbessert ihr nicht nur die Auffindbarkeit für Menschen, sondern auch die spätere Retrieval-Qualität für AI-Systeme. Ein mögliches Beispiel:

Damit schafft ihr eine klare Basis für Governance, Filterung und spätere Knowledge-Base-Nutzung. Gerade in größeren Organisationen ist das oft der Unterschied zwischen brauchbarer und unbrauchbarer Dokumentation.

3. Chunking bewusst designen

Die Qualität eurer späteren AI-Antworten hängt stark davon ab, wie Inhalte segmentiert werden. Für technische Doku ist es meist sinnvoll, entlang von Überschriften, logischen Abschnitten und klar abgrenzbaren Wissenseinheiten zu schneiden. Ein Runbook-Schritt, eine Architekturentscheidung oder eine API-Erklärung sollte als eigene sinnvolle Einheit lesbar bleiben.

4. Diagramme und visuelle Inhalte nicht vergessen

Wenn ein Diagramm wichtig ist, braucht es textlichen Kontext. Ein Architekturdiagramm ohne Beschreibung hilft einem Retrieval-System nur begrenzt. Deshalb sollten Diagramme, Screenshots und Tabellen immer durch erklärenden Text ergänzt werden. So profitieren nicht nur AI-Systeme, sondern auch neue Teammitglieder und fachfremde Leser.

5. Qualitäts-Gates in GitLab etablieren

Konkret zum Beispiel:

• Pflicht-Metadaten im Front Matter
• Automatisierte Link-Checks
• Reviewer-Pflicht via CODEOWNERS
• Owner-Feld pro Dokument
• Review-Datum / Re-Review-Pflicht nach X Monaten
• Checks auf tote Referenzen und fehlende Attachments

Erst dann wird aus „Docs in Git" wirklich ein skalierbares Modell.

Fazit: Gute Strategie, wenn ihr sie richtig versteht

Confluence nach Markdown in GitLab zu migrieren ist keine bloße Formatentscheidung. Es ist eine Architekturentscheidung für Wissen. Technisch ist der Ansatz stark. Businessseitig ist er oft noch stärker. Aber nur dann, wenn ihr ihn nicht als simplen Export-Job behandelt.

Wer es richtig macht, bekommt:

• bessere Versionierung
• robustere technische Dokumentation
• eine sauberere Basis für interne AI-Use-Cases
• weniger Lock-in
• mehr Governance

Wer es falsch macht, bekommt:

• Markdown-Dateien voller Altlasten
• verlorene Semantik
• schlechte Retrieval-Ergebnisse
• neuen Wildwuchs im alten Problem