Microsoft Word ist in vielen Redaktionen nach wie vor Standard. Für die ersten zehn Seiten und die ersten zwei Reviewer funktioniert es. Dann beginnt das Versionschaos: Änderungsverfolgung über Änderungsverfolgung, derselbe Absatz lebt in drei leicht unterschiedlichen Dateien. Dieser Leitfaden zeigt Schritt für Schritt, wie Sie von Word auf einen Docs-as-Code-Workflow umsteigen, mit konkreten Befehlen, Aufräum-Tipps und einem Setup, das mitwächst.

Warum von Word weg?

Word ist ein gutes Textverarbeitungsprogramm. Es ist kein Dokumentationssystem. Der Schmerz beginnt in dem Moment, in dem ein Dokument über einen Autor und ein Release hinauswächst.

  • Track-Changes-Hölle, wenn mehrere Reviewer parallel denselben Absatz kommentieren.
  • Keine echte Modularität. Einen Absatz in drei Handbüchern wiederzuverwenden bedeutet drei Kopien, die auseinanderdriften.
  • Keine Single-Source-Pipeline. PDF-, Web- und Druckversionen entstehen manuell und widersprechen sich schnell.
  • Vendor Lock-in. .docx ist ein komplexes Format, das nur Word und eine Handvoll Klone zuverlässig darstellen.
  • Format-Drift. Überschriften, Listenstile und Tabellenbreiten ändern sich jedes Mal, wenn jemand „nur kurz die Abstände” anpasst.

Docs-as-Code löst diese Probleme, indem Dokumentation wie Quellcode behandelt wird: Klartext, Git, Reviews und automatisierte Builds. Die ausführliche Einordnung finden Sie in unserem Docs-as-Code-Pillar-Artikel. Dieser Leitfaden konzentriert sich ausschließlich auf die Migration von Word.

Was Sie vorher brauchen

Sie brauchen keinen Build-Server. Vier Dinge reichen:

  • Pandoc für die eigentliche Konvertierung. Auf macOS: brew install pandoc. Für Windows oder Linux siehe die Pandoc-Installationsseite.
  • adoc Studio als Editor. Die Community Edition ist kostenlos und reicht für den gesamten Pilot.
  • Git (zunächst optional). Sie können es einführen, sobald das erste Dokument migriert ist.
  • Eine repräsentative Word-Datei. Nehmen Sie ein echtes Dokument, kein Beispiel. Die Konvertierung muss die unordentlichsten Absätze überleben, nicht einen sauberen Testfall.
Der Migrationsfluss in fünf Phasen
Schritt 1 + 2
Vorbereiten
Pilot wählen und Word-Datei aufräumen
→
Schritt 3
Konvertieren
Pandoc wandelt .docx nach AsciiDoc
→
Schritt 4 bis 6
Verfeinern
In adoc Studio aufräumen, modularisieren, stylen
→
Schritt 7
Exportieren
PDF erzeugen und gegen das Original prüfen
→
Schritt 8 + 9
Skalieren
Git aktivieren und auf weitere Dokumente ausrollen

Phase 1: Vorbereiten

Bevor Pandoc übernimmt, entscheidet die Vorarbeit über die Qualität des Ergebnisses. Wählen Sie das richtige Pilotdokument und räumen Sie es so weit auf, dass die Konvertierung sauber durchläuft.

Schritt 1: Inventarisieren und Pilot wählen

Widerstehen Sie der Versuchung, in der ersten Woche alles zu migrieren. Beginnen Sie mit einem Dokument, das die typische Komplexität Ihrer Bibliothek abbildet. Gute Pilotkandidaten haben:

  • ein klares Inhaltsverzeichnis
  • eine Mischung aus Überschriften, Stichpunkt- und nummerierten Listen
  • mindestens ein bis zwei Tabellen
  • eingebettete Bilder
  • Querverweise auf andere Abschnitte

Eine solche Datei zu migrieren bringt 80 Prozent des Wissens für den Rest. Bonus: Sie haben einen echten Vorher-Nachher-Vergleich für Stakeholder.

Schritt 2: Word-Datei vor der Konvertierung aufräumen

Jede Minute Aufräumen im Word-Quelldokument spart zehn Minuten Aufräumen nach der Konvertierung. Öffnen Sie die Pilotdatei und arbeiten Sie folgende Liste ab:

  • Alle Änderungen annehmen und die Änderungsverfolgung deaktivieren.
  • Direkte Formatierung durch Stile ersetzen. Ein fett gemachter Absatz, der eigentlich eine Überschrift ist, muss tatsächlich die Überschriftenformatvorlage nutzen. Pandoc erkennt Struktur über Word-Stile.
  • Tabellen vereinfachen. Verbundene Zellen entfernen, wo möglich. Dekorative Tabellen, die in Wahrheit Layout-Tricks sind, in normale Absätze umwandeln.
  • Eingebettete Objekte exportieren. Excel-Tabellen, Formeln und SmartArt als PNG oder SVG sichern. In diese Objekte kommt Pandoc nicht hinein.
  • Toten Inhalt löschen. Alte Kommentare, ausgeblendeter Text, Notizen aus früheren Runden. Sonst landet der Lärm später im AsciiDoc.

Sie brauchen keine perfekte Word-Datei. Sie brauchen eine, die Stile konsistent nutzt und keine versteckten Überraschungen enthält.

Phase 2: Konvertieren

Jetzt übernimmt Pandoc. Ein einziges Kommando wandelt Ihre .docx-Datei in eine erste AsciiDoc-Fassung samt Bildordner.

Schritt 3: Mit Pandoc konvertieren

Die eigentliche Konvertierung ist ein einziger Befehl. Führen Sie ihn im Ordner mit Ihrer .docx-Datei aus:

pandoc handbook.docx -f docx -t asciidoc --wrap=none --extract-media=./images -o handbook.adoc

Was die Optionen tun:

  • -f docx sagt Pandoc, dass die Quelle eine Word-Datei ist.
  • -t asciidoc legt das Zielformat fest.
  • --wrap=none hält Absätze auf einer einzigen Zeile, was Diffs in Git deutlich sauberer macht.
  • --extract-media=./images zieht jedes eingebettete Bild aus der .docx in einen images/-Ordner neben der AsciiDoc-Datei.
  • -o handbook.adoc ist die Ausgabedatei.

Das Ergebnis ist eine handbook.adoc-Datei plus ein images/-Ordner. Wundern Sie sich nicht über typische Artefakte: tief verschachtelte Listen, leere Absätze, Inline-Style-Spans. Die räumen wir im nächsten Schritt auf.

Phase 3: Verfeinern

Das Rohergebnis aus Pandoc ist die Basis, nicht das Ziel. In adoc Studio räumen Sie auf, ziehen wiederkehrende Bausteine heraus und geben dem Dokument einen sauberen Look.

Schritt 4: In adoc Studio öffnen

Ziehen Sie handbook.adoc in ein neues Projekt in adoc Studio. Aktivieren Sie die Live-Vorschau, damit Sie die gerenderte Ausgabe direkt neben dem Quelltext sehen.

Zwei Aufräumarbeiten lohnen sich sofort:

  • Suchen und Ersetzen für die häufigsten Pandoc-Artefakte. Leere [.underline]-Spans und vereinzelte +++-Blöcke sind typisch.
  • Tabellen reformatieren. AsciiDoc-Tabellen nutzen eine saubere Pipe-Syntax. Einmal neu fließen lassen erleichtert die spätere Pflege erheblich.

Sie sind jetzt zum ersten Mal in einem echten Editor mit strukturierter Sprache und Live-Vorschau. Das Dokument ist nicht mehr in .docx eingesperrt.

Schritt 5: Für Wiederverwendung umstrukturieren

Dieser Schritt macht den Umstieg wirklich lohnenswert. Nehmen Sie die konvertierte Datei und ziehen Sie wiederkehrende Bausteine heraus:

  • Verschieben Sie den Rechtshinweis in _includes/legal-footer.adoc und binden Sie ihn überall dort ein, wo er erscheinen soll.
  • Definieren Sie Produktnamen und Versionsnummern als Attribute am Dateianfang:
    :product-name: Acme CRM
:product-version: 4.2

    Im Fließtext schreiben Sie dann {product-name}. Das Umbenennen des Produkts ist jetzt eine Änderung an einer einzigen Stelle.

  • Glossareinträge, Hinweisboxen und Disclaimer wandern in eigene kleine AsciiDoc-Dateien. Ihr zukünftiges Ich wird sich bedanken.

Übertreiben Sie es am ersten Tag nicht. Refaktorieren Sie, was bereits sichtbar wiederholt wird, den Rest erst, wenn das Muster auftaucht.

Schritt 6: CSS-Stil anwenden

adoc Studio bringt mehrere eingebaute Stile mit, und Sie können auch eine eigene CSS-Datei einbinden. Wählen Sie einen Stil, der zu Ihrer Marke passt, justieren Sie die Typografie in der Live-Vorschau und behalten Sie die CSS-Datei im Projekt. Dieselbe CSS steuert dann sowohl die HTML-Vorschau als auch den PDF-Export.

An dieser Stelle wird der Unterschied auch für Stakeholder sichtbar. Ein sauberes PDF aus Klartext schlägt ein Word-Dokument, das von drei verschiedenen Autorinnen per Hand formatiert wurde.

Phase 4: Exportieren

Jetzt zählt der Vergleich. Ein PDF aus adoc Studio neben dem Original zeigt, ob die Migration die Probe besteht.

Schritt 7: Exportieren und vergleichen

Exportieren Sie das Dokument als PDF aus adoc Studio. Legen Sie es neben das ursprüngliche Word-PDF und gehen Sie diese Checkliste durch:

  • Überschriften erscheinen auf der richtigen Ebene.
  • Tabellen sind intakt, ohne fehlende Zeilen oder verrutschte Zellen.
  • Querverweise zeigen tatsächlich auf das richtige Ziel.
  • Das Inhaltsverzeichnis spiegelt die echte Struktur.
  • Bilder erscheinen am richtigen Ort und in der richtigen Größe.

Was die Prüfung nicht besteht, geht zurück zu Schritt 4. Die meisten Probleme entstehen durch Word-Stile, die nicht konsistent vergeben wurden. Korrigieren Sie die Quelle einmal, lassen Sie Pandoc erneut laufen, fertig.

Phase 5: Skalieren

Was am Pilot funktioniert hat, wiederholen Sie. Git ergänzt Versionierung und Reviews, ein klarer Plan zieht die restliche Bibliothek nach.

Schritt 8: Git hinzufügen, wenn Sie bereit sind

Sie haben den Workflow jetzt an einem Dokument bewiesen. Genau jetzt fängt Git an, sich auszuzahlen.

  • Initialisieren Sie ein Git-Repository im Projekt. adoc Studio bringt Git-Unterstützung mit, ein Terminal ist nicht nötig.
  • Machen Sie den ersten Commit mit dem konvertierten Dokument. Das ist Ihre Baseline.
  • Legen Sie einen Branch für die nächste Bearbeitungsrunde an. Pushen Sie ihn nach GitHub oder GitLab, sobald Fachexpertinnen reviewen sollen.
  • Fachexpertinnen kommentieren direkt im Browser, Zeile für Zeile, im Klartext. Schluss mit „v4_FINAL_marvin_edits.docx”.

Falls Ihr Team noch nicht so weit ist: kein Problem. iCloud-Sync zwischen Mac, iPad und iPhone deckt die meisten Solo- und Klein-Team-Workflows ab.

Schritt 9: Auf den Rest der Bibliothek skalieren

Sobald der Pilot steht, gehen Sie in Wellen vor, nicht in einem Schritt.

  • Gruppieren Sie verbleibende Dokumente nach Typ (Handbücher, Release Notes, interne SOPs). Migrieren Sie einen Typ nach dem anderen.
  • Halten Sie die Lessons Learned aus dem Pilot in einem kurzen Style-Guide fest. Welche Attribute nutzen Sie? Wo liegen Includes? Welche CSS-Klasse gehört zu welchem Dokumenttyp?
  • Bauen Sie ein Projekttemplate. Ein neues Handbuch ist dann „Template kopieren, Attribute ersetzen, schreiben”.

Für umfangreichere Bibliotheken hilft unser No-Nonsense-Migrationsplaybook mit Aufwandsrechner und 30-Tage-Roadmap.

Häufige Stolpersteine

Ein paar Punkte erwischen fast jedes Team. Achten Sie früh darauf:

  • Eingebettete Excel-Tabellen verlieren ihre Formeln. Vorher als echte Tabelle oder Bild exportieren.
  • Formeln aus Words Formel-Editor überleben nicht sauber. In AsciiDoc neu erfassen, mit stem:-Blöcken oder LaTeX.
  • Automatische Nummerierungen für Abbildungen und Tabellen werden in AsciiDoc statisch, sofern Sie die Nummerierung nicht AsciiDoc übergeben. Manuelle Nummern entfernen und die neue Pipeline nummerieren lassen.
  • Querverweise verlieren manchmal ihr Ziel. Suchen Sie nach <<>> und xref: und prüfen Sie jeden Link.
  • Reste der Änderungsverfolgung. Wer Schritt 2 überspringt, findet im AsciiDoc durchgestrichenen Text und Kommentar-Marker. Zurück nach Word, Änderungen annehmen, Pandoc erneut laufen lassen.

Wie es weitergeht

Sie haben jetzt einen funktionierenden Word-zu-AsciiDoc-Workflow mit einem echten Dokument, einem sauberen PDF und der Option, Git hinzuzufügen, sobald Sie es brauchen. Ab hier:

Word ist das richtige Werkzeug für Briefe und Memos. Für Dokumentation, die wächst, ausgeliefert und reviewt wird, zahlt sich der Schritt zu Docs-as-Code bereits beim ersten migrierten Handbuch aus.