Zusammenarbeit

Kommentare im Dokument

Bei der Arbeit im Team sind Kommentare unverzichtbar. AsciiDoc unterstützt zwei Arten von Kommentaren, die nicht in der Ausgabe erscheinen:

Einzeilige Kommentare beginnen mit //:

// TODO: Diesen Abschnitt noch überarbeiten
Hier steht der sichtbare Text.

Block-Kommentare für längere Anmerkungen:

////
Dieser gesamte Block ist ein Kommentar.
Er kann mehrere Zeilen umfassen.
Ideal für ausführliche Notizen oder temporär
ausgeblendete Textpassagen.
////

Kommentare sind nur im Editor sichtbar – in der Vorschau und Ausgabe werden sie ignoriert.

Tipps für effektive Kommentare finden Sie in unserem Blog-Artikel Do’s and Don’ts für Kommentare.

Docs-as-Code

AsciiDoc eignet sich hervorragend für den Docs-as-Code-Ansatz: Dokumentation wird wie Quellcode behandelt und mit denselben Werkzeugen verwaltet.

Vorteile dieses Ansatzes:

  • Versionierung: Änderungen sind nachvollziehbar

  • Zusammenarbeit: Mehrere Autoren können parallel arbeiten

  • Reviews: Änderungen können geprüft werden, bevor sie übernommen werden

  • Automatisierung: Dokumente können automatisch gebaut und veröffentlicht werden

Da AsciiDoc reiner Text ist, lässt es sich optimal mit Git oder anderen Versionskontrollsystemen verwenden.

Versionierung mit Git

AsciiDoc-Dateien sind ideal für Git:

  • Änderungen sind zeilenweise nachvollziehbar

  • Merge-Konflikte lassen sich leicht lösen

  • Branches ermöglichen parallele Dokumentversionen

Typischer Workflow:

  1. Änderungen in einem Branch vornehmen

  2. Pull Request erstellen

  3. Review durch Kollegen

  4. Merge in den Hauptbranch

Schreiben Sie jeden Satz in eine eigene Zeile (Semantic Line Breaks). Das macht Diffs übersichtlicher und erleichtert Reviews.

Automatisierung

adoc Studio lässt sich vollständig automatisieren – ideal für CI/CD-Pipelines und wiederkehrende Aufgaben.

Kommandozeilen-Tool: Mit dem CLI-Tool exportieren Sie Dokumente direkt aus dem Terminal:

adocstudio export --product "Handbuch PDF" --output ./output/

Das Kommandozeilen-Tool können Sie in adoc Studio  Einstellungen …  CLI herunterladen und installieren.

Kurzbefehle-App: Auf dem Mac können Sie Exporte auch über die Kurzbefehle-App automatisieren. Erstellen Sie eigene Shortcuts, die Ihre Produkte auf Knopfdruck exportieren – ohne adoc Studio manuell zu öffnen.

Typische Automatisierungsszenarien:

  • Nächtliche Builds Ihrer Dokumentation

  • Export bei jedem Git-Push

  • Batch-Export aller Sprachversionen

Ein ausführliches Beispiel für Automatisierung finden Sie im Blog-Artikel Automation mit adoc Studio.

Projektwörterbücher

Für Teams, die an vielen verschiedenen Projekten arbeiten, bietet adoc Studio projektspezifische Wörterbücher. So pflegen Sie eine einheitliche Rechtschreibung im Team.

So fügen Sie ein Wörterbuch hinzu:

  1. Aktivieren Sie die Rechtschreibprüfung über Bearbeiten  Rechtschreibung und Grammatik  Während der Texteingabe prüfen

  2. Klicken Sie bei einem unbekannten Wort auf "Lernen"

  3. Wählen Sie ein bestehendes Wörterbuch oder erstellen Sie ein neues

Das neue Wörterbuch (.adict-Datei) erscheint in der Seitenleiste. Es kann versioniert, in andere Projekte übertragen und vom Team gemeinsam genutzt werden.

adoc Studio speichert Projekte als normale Ordner mit AsciiDoc-Dateien. Sie können diese direkt in ein Git-Repository legen und mit Ihrem bevorzugten Git-Client verwalten.