DITA in AsciiDoc mit adoc Studio
Erstellen Sie modulare DITA-Dokumentation mit AsciiDoc in adoc Studio. Speichern Sie Textbausteine zentral und integrieren Sie sie ins Dokument.
Was ist DITA?
Darwin Information Typing Architecture, allgemein bekannt als DITA, ist ein Rahmenwerk für modulares, strukturiertes Schreiben.
DITA gliedert Inhalte in wiederverwendbare Komponenten, die als Topics bezeichnet werden:
Konzepte: Erläutern, was etwas ist.
Aufgaben: Bieten Schritt-für-Schritt-Anweisungen.
Referenzen: Präsentieren strukturierte Informationen wie Tabellen oder Spezifikationen.
Diese Themen werden durch eine DITA Map miteinander verbunden, die die Hierarchie und die Beziehungen des Dokuments definiert. Dieses System ist maßgeschneidert für technische Redakteure, die mit der Komplexität umgehen müssen.
XML versus AsciiDoc
Während DITA XML verwendet, das mit seiner Ausführlichkeit überwältigend sein kann, bietet AsciiDoc eine sauberere, besser lesbare Syntax. adoc Studio ermöglicht es Ihnen, in AsciiDoc zu schreiben und dabei die strukturierte Logik von DITA beizubehalten.
Hier sehen Sie, warum AsciiDoc in adoc Studio XML für DITA-ähnliche Projekte übertrifft:
Lesbar und doch leistungsfähig: Im Gegensatz zur ausführlichen XML-Syntax ist AsciiDoc übersichtlich und intuitiv und unterstützt dennoch wesentliche Elemente wie Tabellen und Zitate - ohne Erweiterungen oder zusätzliche Tools.
Eingebaute Hilfe: XML erfordert eine strenge Formatierung und ständige Bezugnahme auf Schemata. Im Gegensatz dazu führt Sie der adoc Coach von adoc Studio mit Echtzeit-Syntaxunterstützung, wodurch Fehler reduziert und Ihr Arbeitsablauf beschleunigt wird.
Sofortige Vorschauen: Bei XML sind Sie oft auf externe Konverter und mühsames Hin und Her angewiesen, um eine Vorschau der Inhalte zu erhalten. adoc Studio bietet eine dynamische HTML- und PDF-Vorschau und exportiert direkt, so dass keine externe Verarbeitung erforderlich ist.
Hier ist ein Vergleich, der die Ausführlichkeit von XML gegenüber der Einfachheit von AsciiDoc bei der Erstellung einer Tabelle - einem gängigen Syntaxelement in strukturierten Dokumenten - verdeutlicht:
In XML: 483 Zeichen
<table>
<title>Comparison Table</title>
<tgroup cols="3">
<thead>
<row>
<entry>Feature</entry>
<entry>AsciiDoc</entry>
<entry>XML</entry>
</row>
</thead>
<tbody>
<row>
<entry>Syntax</entry>
<entry>Simple</entry>
<entry>Verbose</entry>
</row>
<row>
<entry>Flexibility</entry>
<entry>High</entry>
<entry>Moderate</entry>
</row>
</tbody>
</tgroup>
</table>In AsciiDoc: 105 Zeichen
.Comparison Table
|===
|Feature |AsciiDoc |XML
|Syntax |Simple |Verbose
|Flexibility |High |Moderate
|===Wie man ein DITA-ähnliches Projekt in adoc Studio einrichtet
Lassen Sie uns nun ein Beispielprojekt nach der DITA-Struktur in adoc Studio anlegen.
1. Erstellen einer standardisierten Dateistruktur
Zunächst wollen wir eine modulare Dateistruktur erstellen, die sich im Laufe der Zeit für weitere Kunden skalieren lässt. Hierfür benötigen wir drei Komponenten:
Kundenkomponenten: Ein individueller Ordner für jeden Kunden.
Beispieldateien für jeden Kunden: customer-details.adoc & contract-specifications.adoc
Globale Komponenten: Ein zentraler Ordner für alle Dateien, die in mehreren Projekten verwendet werden.
Beispieldateien: über-uns.adoc & terms.adoc
Projekt-Map: Kombiniert globale und kundenspezifische Komponenten dynamisch. Für dieses Beispiel nennen wir sie Contracts.ads
Daraus ergibt sich diese Dokumentstruktur:
Documents/
├── Contracts.ads/
│ ├── Contract.adocproject/
│ ├── local-file.adoc/
│ ├── Media/
│ ├── project-map.adoc/
├── Customers/
│ ├── adoc Studio/
│ │ ├── customer_details.adoc
│ │ ├── contract-specifications.adoc
│ │ ├── ...
│ ├── Customer_A/
│ │ ├── customer_details.adoc
│ │ ├── ...
│ ├── Customer_B/
│ │ ├── customer_details.adoc
│ │ ├── ...
├── Global Components/
│ ├── about-us.adoc
│ ├── terms.adoc
│ ├── ...2. Erstellen Sie die Projektübersicht
Die Project Map dient als zentraler Knotenpunkt für Ihre Dokumentation und vereint globale und kundenspezifische Komponenten. Sie ist sozusagen das Äquivalent zu einer DITA-Map.
In adoc Studio erstellen wir ein neues Projekt mit dem Namen contract.adocproject und verwenden die include::[] Direktive, um Dateien nahtlos zu integrieren.
Interne Interne Dateien
Dateien, die im gleichen Verzeichnis wie Ihr Projekt gespeichert sind, können direkt durch Verweis auf ihren Dateinamen eingebunden werden. So bleibt alles in sich geschlossen und leicht zu verwalten.
Tipp: Verwenden Sie den adoc Coach von adoc Studio, um sich in Echtzeit über die korrekte Einrichtung der include::[]-Syntax zu informieren. Drücken Sie einfach die ESC-Taste oder geben Sie die ersten Buchstaben der Syntax incl ein und der Coach öffnet sich automatisch und schlägt die richtige Syntax vor.
Externe Dateien über relative Pfade einbinden
Für Dateien, die sich außerhalb des Projektverzeichnisses befinden, sollten Sie relative Pfade verwenden. Diese Methode gewährleistet die Modularität und Wiederverwendbarkeit von gemeinsam genutzten Inhalten.
../: Bewegt sich eine Verzeichnisebene nach oben.Zusätzliche
../: Jedes zusätzliche../verschiebt den Verzeichnisbaum um eine weitere Ebene nach oben.Nachdem Sie nach oben navigiert haben, geben Sie den Ordner und die Datei an, die Sie einschließen möchten.
Dieser Ansatz eignet sich hervorragend für die Einbindung globaler Komponenten wie Begriffe oder Unternehmensinformationen und gewährleistet die Konsistenz über mehrere Projekte hinweg.
Externe Dateien über absolute Pfade einbinden
Bei Bedarf können Sie auch absolute Pfade verwenden, um auf Dateien zu verweisen. Diese Methode geht vom Stammverzeichnis aus (z. B. file:/absolute/path/to/file.adoc). Absolute Pfade sind robust und verringern die Abhängigkeit von der Projektstruktur, sind aber möglicherweise weniger portabel.
Dynamische kundenspezifische Dateien
Binden Sie kundenspezifische Dateien dynamisch ein, indem Sie ein Attribut wie :customer: in Ihrer Project Map definieren und den Verweis {customer} zu Ihrem Dateipfad innerhalb der include-Direktive hinzufügen.
Aktualisieren Sie dann das Attribut, um einfach zwischen den Kunden zu wechseln.
3. Exkurs: Bedingungen festlegen, um Informationen einzubetten oder auszuschließen
Mit Bedingungen und Attributen können Sie Ihre Dokumente auf bestimmte Zielgruppen zuschneiden und flexible Ausgaben erstellen, ohne Dateien zu duplizieren.
Wenn Sie beispielsweise interne Kommentare für jeden Kunden in Dateien wie internal-comments-adoc-studio.adoc verwalten, können Sie diese in die internen Exporte für Ihr Team aufnehmen. Der richtige Kommentar wird dynamisch für jeden Export eingebettet, indem ein Attribut für den Kundennamen verwendet wird.
Verwenden Sie Attribute wie :internal: in Ihrem Produkt, um die Sichtbarkeit dynamisch umzuschalten.
Mit diesen Exportoptionen stellt adoc Studio sicher, dass Sie jede Dokumentationsherausforderung bewältigen können, egal ob es sich um eine einmalige Kundenanforderung oder einen Stapel von benutzerdefinierten Ausgaben handelt.
:customer: adoc Studio
:internal:
ifdef::internal[]
include::internal-comments-{customer}.adoc
endif::[]4. Exportieren Sie Ihr Projekt
Nachdem wir nun eine Projektübersicht erstellt und Attribute und Bedingungen hinzugefügt haben, können wir einen ersten Export des neuen Vertrags erstellen.
Hierfür gibt es zwei Möglichkeiten: Entweder Sie exportieren die Datei direkt, oder Sie richten ein Produkt ein, um Exporteinstellungen wie Attribute für die Wiederverwendung zu speichern.
Sind Sie bereit, Ihren Workflow zu optimieren?
Beginnen Sie mit der Erstellung DITA-ähnlicher modularer Dokumentation mit AsciiDoc in adoc Studio. Kombinieren Sie Einfachheit, Flexibilität und Leistung in einem Werkzeug. Melden Sie sich für eine 14-tägige kostenlose Testversion an und erleben Sie die nahtlose Dokumentationserstellung noch heute.
