Mit neuem Plug-in clever kombinieren

Text: Martin Kreutzer Mark Schubert

Das iiRDS-Konsortium hat ein Plug-in zur Unterstützung von DITA-Inhalten vorgestellt. Es ist einfach zu bedienen und kann individuell für ein Projekt angepasst werden.

Inhaltsübersicht

Lesedauer: 04:08 Minuten

Darwin Information Typing Architecture, kurz „DITA“, ist ein etablierter Authoring-Standard. Er ist gut strukturiert, anpassbar und wird von einem Open-Source-Toolkit unterstützt: das DITA Open-Toolkit, kurz „DITA-OT“. Mit DITA-OT können Sie etwa HTML oder PDF aus Ihren DITA-Dateien erzeugen. Single-Source-Publishing macht es möglich – eine der Kernideen von DITA und DITA-OT.

Durch die Trennung von Informationen in Topic-Typen und XML als Grundlage ist DITA für die heutigen Anforderungen der Technischen Kommunikation bestens geeignet. Mit Microcontent als neuem Goldstandard ermöglicht DITA die Erstellung granularer Informationen. Diese fließen in Content-Delivery-Portale, Chatbots und KI-basierte Szenarien wie Retrieval-Augmented Content Generation ein.

Darum bringt es iiRDS

Damit Mikroinhalte nützlich sind, benötigen sie Metadaten. Hier kommt der intelligent information Request and Delivery Standard (iiRDS) ins Spiel. Sowohl DITA als auch iiRDS sind topicorientiert und ermöglichen es Benutzerinnen und Benutzern, genau die Informationen zu erhalten, die sie benötigen. Dazu stellt iiRDS ein Austauschformat zur Verfügung. Es wird häufig verwendet, um Technische Dokumentation aus Content-Management-Umgebungen in Content-Delivery-Szenarien zu veröffentlichen.

Dafür definiert iiRDS ein Paketierungsformat und ein erweiterbares Metadatenschema. Das Paketierungsformat ist ein ZIP-Container. Er enthält die Inhaltsdateien und Metadaten (Abb. 01). Diese Metadaten sind nicht Teil des Inhalts, sondern eine separate Datei. Diese umfasst Metadaten über den Inhalt in Form des W3C-Standards RDF. Mit RDF (Resource Description Framework) können Sie Subjekt-Prädikat-Objekt-Aussagen über alles Mögliche machen, zum Beispiel „Thema A – handelt von – Produkt B“. Solche Metadaten benötigen wir für unsere Mikroinhalte (Abb. 01).

Struktur eines iiRDS-Pakets.
Abb. 01 iiRDS-Paket mit Inhalts- und Metadatenordnern. Quelle Martin Kreutzer und Mark Schubert

Bereits seit 2016 gibt es iiRDS. Heute wird der Standard von vielen Content-Delivery-Portalen unterstützt. DITA-OT wurde jedoch bisher nur durch Plug-ins unterstützt, die als Proof-of-Concept gedacht waren. Die Plug-ins erforderten spezielle XML-Elemente, ließen sich nur schwer in bestehende Projekte integrieren und hatten keine Dokumentation. Im Jahr 2023 beauftragte das iiRDS-Konsortium ein neues Plug-in. Das von der Empolis Information Management GmbH (Kaiserslautern) entwickelte und von der parson AG (Hamburg) getestete und dokumentierte Plug-in ist jetzt verfügbar. Es erstellt ein iiRDS-Paket, ist einfach zu bedienen und kann an die individuellen Anforderungen eines Projekts angepasst werden.

So funktioniert das Plug-in

Das iiRDS-Plug-in integriert sich nahtlos in das DITA-OT und funktioniert wie vom DITA-OT gewohnt. Nach der Installation stellt es einen neuen Transformationstyp „iirds“ zur Verfügung. Mit diesem Transformationstyp erhalten Sie ein iiRDS-Paket, das HTML-Dateien für jede Ihrer DITA-Topic-Dateien enthält. Das Paket hat auch eine „metadata.rdf“-Datei. Diese Datei umfasst Metadaten für alle HTML-Dateien im iiRDS-Paket (Abb. 02).

iiRDS-Metadaten und HTML.
Abb. 02 iiRDS-Metadaten eines Topics, das einer HTML-Datei zugeordnet ist. Quelle Martin Kreutzer und Mark Schubert

Die Metadaten werden von den XML-Elementen und Attributen in den DITA-Dateien abgeleitet. Zum Beispiel werden die iiRDS-Metadaten „Component“ von dem XML-Element „component“ abgeleitet, während die iiRDS-Metadaten „ProductVariant“ aus der Kombination des Elements „prodname“ und des Attributs „product“ abgeleitet werden.

Auch wenn keine expliziten Metadaten in der DITA-Datei vorhanden sind, generiert das Plug-in nützliche iiRDS-Pakete mit Dokumenten, Topics, Topic-Typen und einer Navigationsstruktur. Da das Hauptziel des neuen Plug-ins jedoch darin bestand, die Nutzung zu vereinfachen, werden nicht alle iiRDS-Metadaten von Haus aus unterstützt. Was zunächst wie ein Nachteil erscheint, ist in Wirklichkeit eine der größten Verbesserungen des neuen Plug-ins: Sie können Ihre DITA-Inhalte, sogar spezielles DITA-XML, verwenden und iiRDS-Pakete generieren. Die einzige Herausforderung besteht darin, die Anbieter davon zu überzeugen, Ihnen ein Content-Delivery-Portal zum Import Ihrer iiRDS-Pakete zur Verfügung zu stellen (Abb. 03).

Inhalt mit DITA markiert und Darstellung in einem Portal.
Abb. 03 DITA-Inhalt (links) und resultierendes Topic in einem Content-Delivery-Portal (rechts). Quelle Martin Kreutzer und Mark Schubert

So kann es angepasst werden

Mit dem neuen iiRDS Plug-in sind Sie schnell startklar. Aber vielleicht wollen Sie noch mehr. Und das neue Plug-in bietet auch mehr. Grundsätzlich kann jeder Aspekt der iiRDS-Paketgenerierung angepasst werden, einschließlich:

  • HTML-Aussehen und -Bedienung
  • Extraktion von Metadaten
  • Metadaten-Bezeichner
  • Verarbeitungsschritte

Das iiRDS-Paket enthält die grundlegenden, von DITA-OT generierten HTML-Dateien. Das iiRDS-Plug-in unterstützt jedoch alle DITA-OT-Transformationsparameter zur Anpassung von HTML. Sie können Ihre eigenen Dateien zur Darstellung bzw. Transformation verwenden (CSS bzw. XSLT). Dadurch wird das iiRDS-Paket um Ihr eigenes HTML ergänzt.

Wir haben gesehen, dass sich bei iiRDS alles um Metadaten dreht. Da iiRDS von vornherein auf bestimmte Metadaten beschränkt ist, möchten Sie vielleicht die Java-basierte Metadatenextraktion anpassen. Sie können dies tun, indem Sie Ihre eigenen Metadatenextraktoren registrieren und alle Ihre Metadatenelemente und -attribute unterstützen. Sie möchten das Element „component“ nicht verwenden, aber Ihre eigenen gruppierten Attributwerte in Ihrem spezialisierten Attribut nutzen? Implementieren Sie die Java-Service-Provider-Schnittstelle des „IirdsMetadataHandler“ – und schon sind Sie startklar.

Bezeichner sind ein eher technischer Aspekt. Um den Inhalten Metadaten zuzuordnen, muss dies auf einheitliche und stabile Weise geschehen. Wenn sich etwa der Bezeichner für die Komponente „Dichtung“ im Laufe der Zeit ändert, ist in einem Content-Delivery-Portal nicht erkenntlich, dass es sich um dieselbe Komponente handelt. Aber genau wie bei den Metadaten-Extraktoren können Sie Ihren eigenen Java-Service-Provider implementieren und die Standardzuweisung von Bezeichnern anpassen.

Schließlich können Sie mit dem iiRDS-Plug-in Ihre eigenen Verarbeitungsschritte hinzufügen. DITA-OT-Erweiterungspunkte ermöglichen es Ihnen, Ihre eigene ANT-Targets hinzuzufügen.

Alles in allem ist das Plug-in bereit für den Produktiveinsatz. Die Code-Basis ist getestet, die Funktionalität ist dokumentiert, und bei projektspezifischen Anforderungen können Sie es mit Parametern oder eigenen zusätzlichen Plug-ins anpassen.

Ein Zeigefinger schiebt ein Teil eines Puzzles.