© Excellent backgrounds/Shutterstock.com
Kolumne: Hitchhiker’s Guide to Docs as Code

Kolumne: Hitchhiker’s Guide to Docs as Code


Architekturdokumentation besteht hauptsächlich aus Fließtext, Tabellen und Diagrammen. Fließtext und Tabellen sollten nach der letzten Folge kein Problem mehr sein. Jetzt zeigen wir Ihnen mehrere Optionen, Diagramme in Ihre Dokumentation zu integrieren: Einerseits den einfachen Weg des Referenzierens (mit einigen möglichen Optionen) und alternativ Diagrams as Code, was gut zu Titel und Inhalt dieser Kolumne passt. So viel sei allerdings schon verraten: Leider eignet sich der letztgenannte PlantUML-basierte Ansatz nur für ganz wenige Arten von Diagrammen. Aber eins nach dem anderen: Fangen wir mit den einfachen Dingen an.

Wenn wir davon sprechen, Diagramme zu verwenden, meinen wir in der Regel die Integration eines Diagramms, das als eigenständige Grafikdatei (etwa als JPG, PNG oder SVG) existiert, in unsere AsciiDoc-basierte Dokumentation. Diese Grafik muss zum Build-Zeitpunkt an einem definierten Platz liegen, dem sogenannten Image Directory. Zu unserem Diagramm oder Bild hätten wir gerne eine Unterschrift sowie eine fortlaufend vergebene Bild-/Diagrammnummer. Wie einfach die AsciiDoc-Lösung dafür aussieht, zeigen wir am Beispiel eines noch nicht weltbekannten Logos. Abbildung 1 enthält eine Vorschau auf das Ergebnis.

.Das HHGDAC-Logo image::hhgdac-logo.png["alternate-text"]
mueller_starke_1.tif_fmt1.jpgAbb. 1: Logo der Kolumne

Styling ist alles, oder?

Ach ja, bei Bedarf möchten Sie Ihre Diagramme etwas stylen, etwa Größe und Ausrichtung anpassen, mehrere Diagramme nebeneinander zeigen und das englische Wort Figure durch Abbildung ersetzen (Abb. 2). Auch dafür hat AsciiDoc einfache Mittel an der Hand (Listing 1). Wir haben unser Logo in drei verschiedenen Größen verwendet und verwenden als Bildunterschrift jetzt „Abbildung“. Mit der figure-caption benennen wir die Standardbildunterschrift um. Bei jedem Diagramm geben wir an, ob es links-, rechtsbündig oder zentriert angezeigt werden soll. Das können wir innerhalb der [] nach dem Dateinamen schreiben oder vor dem eigentlichen image-Tag. In die float-group können Sie auch noch Textabsätze aufnehmen, die stellt AsciiDoc dann neben die entsprechenden Bilder. Das ist manchmal ganz nützlich, wenn Sie neben schmalen Abbildungen noch erläuternden Text platzieren möchten.

mueller_starke_2.tif_fmt1.jpgAbb. 2: Bilder gestylt

Vorsicht: Nutzen Sie Stylinganweisungen nur in Ausnahmefällen, weil das gegen die gute Idee der Trennung von Inhalt und Layout verstößt! Wir finden es allerdings nützlich, über diese Optionen zu verfügen, sie könnten (!) ja mal hilfreich sein. In HTM...

Neugierig geworden?

Angebote für Teams

Für Firmen haben wir individuelle Teamlizenzen. Wir erstellen Ihnen gerne ein passendes Angebot.

Das Library-Modell:
IP-Zugang

Das Company-Modell:
Domain-Zugang