Seminar Antora – Content-Komponenten, Module und Navigation

Beschreibung

Das Seminar vermittelt die zentrale Inhaltsarchitektur von Antora. Komponenten, Versionen, Module, Ressourcenfamilien und Navigationsdateien werden so aufgebaut, dass umfangreiche Dokumentationsbestände verständlich, wartbar und über mehrere Releases hinweg konsistent bleiben. Die Übungen führen von einer ungeordneten Sammlung von AsciiDoc-Dateien zu einem belastbaren Komponentenmodell mit prüfbaren Navigations- und Freigaberegeln.

Inhaltsübersicht

1. Inhaltsmodell und Benennungsregeln
2. Komponenten-Deskriptor antora.yml
3. Module und Ressourcenfamilien
4. Navigation planen und implementieren
5. Versionen und Komponentenbeziehungen
6. Strukturqualität und Governance

Lernziele

• Komponenten, Versionen und Module fachlich nachvollziehbar abgrenzen.
• Ressourcenfamilien regelkonform strukturieren und referenzierbar benennen.
• Navigationsdateien für große und versionierte Dokumentationsbestände entwerfen.
• Strukturfehler mit reproduzierbaren Prüf- und Freigabeschritten erkennen.

1. Inhaltsmodell und Benennungsregeln

Der Einstieg schafft ein gemeinsames Modell für Komponenten, Versionen, Module und Ressourcenfamilien.

Schritt-für-Schritt: Eine fachliche Domäne in ein Antora-Inhaltsmodell überführen

1. Produkte, Plattformteile, Zielgruppen und Release-Linien als fachliche Einheiten erfassen.
2. Für jede Einheit entscheiden, ob sie eine Komponente, eine Version oder ein Modul bildet.
3. Namensregeln für Komponenten, Module, Seiten, Bilder, Beispiele, Anhänge und Partials definieren.
4. Grenzfälle wie gemeinsam genutzte Inhalte, Querschnittsthemen und produktübergreifende Anleitungen kennzeichnen.
5. Das Modell anhand von Wartbarkeit, Verantwortlichkeit und Referenzierbarkeit überprüfen.

Praxisaufgabe

Ein unstrukturierter Dokumentationsbestand wird in ein begründetes Komponenten- und Modulmodell zerlegt.

2. Komponenten-Deskriptor antora.yml

Der Komponenten-Deskriptor steuert Identität, Version, Navigation und optionale Metadaten einer Inhaltsquelle.

Schritt-für-Schritt: Einen vollständigen Komponenten-Deskriptor erstellen und prüfen

1. Im Stamm der gewählten Startpfade eine Datei antora.yml anlegen.
2. Komponentenname, Anzeigename und Version eindeutig und konsistent eintragen.
3. Navigationsdateien in der gewünschten Reihenfolge deklarieren.
4. Optionale Attribute und Metadaten nur dort ergänzen, wo sie für Inhalte oder UI benötigt werden.
5. Einen lokalen Build ausführen und Warnungen zu Deskriptor, Version oder Navigation gezielt auswerten.
6. Den Deskriptor mit einem Review-Schema für weitere Repositories standardisieren.

Praxisaufgabe

Mehrere fehlerhafte Deskriptoren werden korrigiert und in eine einheitliche Konvention überführt.

3. Module und Ressourcenfamilien

Module ordnen Seiten und zugehörige Ressourcen in klar abgegrenzte Inhaltsräume.

Schritt-für-Schritt: Eine modulare Verzeichnisstruktur aufbauen

1. Für jedes geplante Modul das Verzeichnis modules/<modulname> anlegen.
2. Die Familien pages, images, examples, attachments und partials bedarfsgerecht ergänzen.
3. Bestehende Dateien nach Zweck und Wiederverwendungspotenzial den passenden Familien zuordnen.
4. Dateinamen vereinheitlichen und problematische Sonderzeichen oder uneindeutige Namen beseitigen.
5. Nicht benötigte leere Familien vermeiden und die Struktur mit einer Checkliste kontrollieren.
6. Den Build ausführen und stichprobenartig prüfen, ob Ressourcen unter der erwarteten Identität verfügbar sind.

Praxisaufgabe

Eine gemischte Sammlung aus Seiten, Bildern, Codebeispielen und Downloads wird in zwei Module überführt.

4. Navigation planen und implementieren

Navigation bildet den vorgesehenen Lern- und Arbeitsweg ab und darf nicht mit der bloßen Dateistruktur verwechselt werden.

Schritt-für-Schritt: Eine nutzerorientierte Navigation erstellen

1. Primäre Aufgaben und Informationsbedarfe der Zielgruppen als Navigationsszenarien formulieren.
2. Pro Modul eine oder mehrere Navigationsdateien mit geeigneten Ebenen und Bezeichnungen anlegen.
3. Seiten mit eindeutigen Ressourcen-IDs einbinden und reine Strukturüberschriften gezielt einsetzen.
4. Mehrere Navigationsdateien im Komponenten-Deskriptor in der gewünschten Reihenfolge registrieren.
5. Navigation auf fehlende Ziele, Doppelungen, zu tiefe Hierarchien und unverständliche Bezeichnungen prüfen.
6. Die Navigation mit einem aufgabenbasierten Test durch repräsentative Nutzerrollen abnehmen.

Praxisaufgabe

Für eine Produktdokumentation wird eine aufgabenorientierte Navigation mit Einstiegs-, Referenz- und Betriebsbereich aufgebaut.

5. Versionen und Komponentenbeziehungen

Versionierte Inhalte erfordern klare Regeln für aktuelle, ältere, unveröffentlichte und gemeinsam genutzte Inhalte.

Schritt-für-Schritt: Ein konsistentes Versionsmodell konfigurieren

1. Release-Linien und Lebenszyklusstatus der Dokumentation erfassen.
2. Branches, Tags oder feste Startpfade den vorgesehenen Komponenten-Versionen zuordnen.
3. Anzeigenamen und Sortierlogik für aktuelle, ältere und Entwicklungsstände definieren.
4. Querverweise zwischen Versionen nur dort zulassen, wo der fachliche Zusammenhang stabil ist.
5. Gemeinsame Inhalte auf Duplizierung, Kopplung und Eigentümerschaft prüfen.
6. Mehrere Versionen bauen und Navigation, Versionsumschalter sowie Referenzen gegeneinander testen.

Praxisaufgabe

Eine Komponente mit aktuellem Release, Wartungsrelease und Entwicklungsstand wird modelliert und geprüft.

6. Strukturqualität und Governance

Ein tragfähiges Inhaltsmodell benötigt Regeln, Prüfpunkte und Verantwortlichkeiten für den laufenden Betrieb.

Schritt-für-Schritt: Strukturregeln als wiederholbaren Qualitätsprozess etablieren

1. Verbindliche Kriterien für neue Komponenten, Module und Navigationsknoten formulieren.
2. Code-Review-Prüfpunkte für Deskriptor, Dateistruktur, Benennung und Navigation definieren.
3. Automatisierbare Prüfungen für fehlende Dateien, ungültige IDs und nicht registrierte Navigation festlegen.
4. Eigentümer für Komponenten und Querschnittsinhalte benennen.
5. Änderungen am Inhaltsmodell über dokumentierte Architekturentscheidungen steuern.
6. Einen regelmäßigen Struktur-Review mit Kennzahlen und Nacharbeitsprozess planen.

Praxisaufgabe

Als Arbeitsergebnis entsteht eine Governance-Checkliste für Pull Requests und neue Dokumentationskomponenten.

Zielgruppe und Voraussetzungen

Zielgruppe: Technische Redakteure, Documentation Engineers, Content-Architekten, Softwareteams mit Dokumentationsverantwortung und Plattformadministration.

Voraussetzungen: Grundkenntnisse in AsciiDoc und Git sowie ein grundlegendes Verständnis statischer Dokumentationssites.

Methodik und Arbeitsweise

Die Inhalte werden durch strukturierte Erläuterungen, Demonstrationen, schrittweise Konfigurations- und Analyseaufgaben sowie kontrollierte Fehlerfälle vertieft. Jede Übung verwendet definierte Ausgangswerte, Prüfpunkte und Dokumentationsanforderungen, damit die erarbeiteten Abläufe im späteren Projekt- und Betriebsalltag reproduzierbar bleiben.