Dokumentation scheitert selten daran, dass niemand schreiben kann. Häufiger werden unterschiedliche Aufgaben in ein einziges Dokument gepackt: ein bisschen Einführung, einige Befehle, eine unvollständige Referenztabelle und dazwischen die Geschichte, warum das System überhaupt existiert.
Menschen finden darin nur mit Geduld die richtige Information. KI kann den Text zwar zusammenfassen, übernimmt dabei aber leicht die Vermischung.
Zwei einfache Grundlagen helfen: Markdown sorgt für ein lesbares und portables Format. Diátaxis trennt vier verschiedene Bedürfnisse der Leser.
Markdown: Struktur ohne schweres Dateiformat
Markdown ist ein Klartextformat für strukturierte Dokumente. Überschriften, Listen, Links, Zitate und Code bleiben bereits im Quelltext erkennbar. Der Inhalt lässt sich mit vielen Werkzeugen lesen, versionieren und in andere Formate umwandeln.
Das ist für dauerhafte Dokumentation nützlich:
- Änderungen sind in Git präzise vergleichbar.
- Dateien bleiben ohne Spezialsoftware lesbar.
- Links und Überschriften liefern maschinenlesbare Struktur.
- Inhalte können in Websites, PDFs oder Wissenssysteme übernommen werden.
- Automatische Prüfungen können Format, Links und Metadaten kontrollieren.
CommonMark versucht, die ursprünglich mehrdeutige Markdown-Syntax eindeutig zu spezifizieren. Das reduziert Überraschungen zwischen unterschiedlichen Parsern. Erweiterungen wie Tabellen oder Fußnoten können sinnvoll sein, sollten aber bewusst gewählt werden. Jede proprietäre Sonderform verringert die Portabilität ein Stück.
Markdown allein macht Dokumentation allerdings nicht gut. Ein chaotischer Text bleibt auch mit hübschen Rauten chaotisch.
Diátaxis: Vier Bedürfnisse statt eines Universaltextes
Diátaxis unterscheidet vier Dokumentationsformen:
- Tutorial: führt Lernende unter Anleitung zu einem ersten Erfolg.
- How-to-Anleitung: hilft einer bereits handlungsfähigen Person, ein konkretes Ziel zu erreichen.
- Referenz: beschreibt das System präzise und vollständig.
- Erklärung: vermittelt Hintergründe, Zusammenhänge und Gründe.
Diese Formen unterscheiden sich nicht nur im Ton. Sie beantworten verschiedene Fragen.
Ein Tutorial fragt: „Wie lerne ich den grundlegenden Ablauf?“ Eine How-to-Anleitung fragt: „Wie löse ich dieses konkrete Problem?“ Die Referenz fragt: „Welche Optionen und Regeln gibt es?“ Die Erklärung fragt: „Warum funktioniert oder existiert das so?“
Wer alle vier Aufgaben vermischt, erzeugt ein Dokument, das für jede Zielgruppe ein bisschen und für keine richtig funktioniert.
Warum diese Trennung KI hilft
Eine KI muss nicht nur Text finden, sondern die Absicht des Textes verstehen. Die Kennzeichnung als Tutorial, Anleitung, Referenz oder Erklärung liefert dafür ein starkes Signal.
Bei der Frage „Welche Parameter akzeptiert der Befehl?“ sollte die Referenz Vorrang haben. Bei „Warum verwenden wir dieses Architekturprinzip?“ ist eine Erklärung geeigneter. Für „Führe mich durch die erste Einrichtung“ braucht es ein Tutorial.
Ohne diese Unterscheidung kann ein Modell eine vereinfachte Tutorial-Aussage als vollständige technische Regel behandeln oder eine Hintergrunddiskussion in eine operative Anleitung mischen.
Ein Beispiel: Backup-Dokumentation
Eine einzige Seite „Backups“ wird schnell unübersichtlich. Nach Diátaxis entstehen vier klarere Dokumente:
Tutorial: Erstes Test-Backup erstellen
Es führt Schritt für Schritt durch eine sichere Übungsumgebung. Das Ziel ist Lernen, nicht maximale Vollständigkeit.
How-to: Einzelne Datei wiederherstellen
Es setzt Grundkenntnisse voraus und beschreibt nur den konkreten Wiederherstellungsweg.
Referenz: Aufbewahrungsregeln und Befehlsoptionen
Sie enthält vollständige Parameter, Pfade, Fristen und technische Grenzen.
Erklärung: Warum wir 3-2-1-Backups verwenden
Sie erläutert Risiken, Abwägungen und die gewählte Strategie.
Die Dokumente dürfen sich verlinken. Sie sollten ihre Aufgaben aber nicht gegenseitig übernehmen.
Eine brauchbare Markdown-Grundstruktur
Für viele Dokumente genügt ein kleiner Standard:
---
type: how-to
status: approved
owner: platform-team
reviewed: 2026-07-31
---
# Einzelne Datei wiederherstellen
Kurzer Zweck und erwartetes Ergebnis.
## Voraussetzungen
## Vorgehen
## Prüfung
## Fehlerbehebung
## Verwandte Dokumente
Die Metadaten zeigen, was das Dokument ist, ob es gilt, wer es pflegt und wann es zuletzt geprüft wurde. Die Überschriften strukturieren den Ablauf. Links verbinden Referenz und Hintergrund, ohne beides zu kopieren.
Wo KI unterstützen kann
KI kann bei dokumentierter Struktur sinnvoll helfen:
- einen vorhandenen Text einer Diátaxis-Form zuordnen,
- vermischte Abschnitte erkennen,
- aus einer Referenz einen How-to-Entwurf ableiten,
- fehlende Voraussetzungen oder Prüfschritte markieren,
- Links zwischen verwandten Dokumenten vorschlagen,
- unverständliche Passagen vereinfachen,
- Dokumentation gegen Code oder Konfiguration vergleichen.
Sie sollte nicht ungeprüft aus einem Tutorial eine verbindliche Referenz erzeugen. Vereinfachung ist dort erwünscht; Vollständigkeit nicht.
Portabilität braucht Disziplin
Markdown verführt dazu, jede Plattformerweiterung mitzunehmen: spezielle Callouts, eingebettete Datenbankabfragen, proprietäre Linksyntax und ausführbare Blöcke. Das kann produktiv sein, bindet den Bestand aber stärker an ein Werkzeug.
Eine vernünftige Regel lautet:
- Kerninhalte in standardnahem Markdown,
- Metadaten in einfachem YAML,
- Erweiterungen nur mit erkennbarem Nutzen,
- wichtige Aussagen nie ausschließlich in proprietären Darstellungen,
- automatische Prüfung der verwendeten Konventionen.
Portabilität bedeutet nicht, auf jede nützliche Funktion zu verzichten. Sie bedeutet, Abhängigkeiten bewusst zu machen.
Fazit
Markdown und Diátaxis lösen zwei verschiedene Probleme. Markdown hält Inhalte lesbar, versionierbar und transportabel. Diátaxis sorgt dafür, dass ein Dokument eine klare Aufgabe erfüllt.
Zusammen entsteht Dokumentation, die Menschen schneller einordnen und KI gezielter verwenden kann. Das ist weniger glamourös als ein Chatbot, der angeblich jede Frage beantwortet. Dafür bleibt die Antwort auch dann nachvollziehbar, wenn das Modell wechselt.
