Eintägige DITA-Schulung (Online, Adobe FrameMaker)

Was ist DITA

DITA (Darwin Information Typing Architecture) ist eine XML-basierte Architektur für technische Dokumentation. Sie ermöglicht die Erstellung modularer, wiederverwendbarer und semantisch strukturierter Inhalte. Anstatt lange Fließtexte zu schreiben, gliedern Sie Informationen in Topics – in sich geschlossene Bausteine wie Konzepte, Anleitungen (Tasks) oder Referenzen. Mehrere Topics werden in einer DITA-Map zusammengestellt, die als Struktur- und Navigationsgerüst (ähnlich einem Inhaltsverzeichnis) dient. DITA unterstützt zudem Domains, also spezialisierte Erweiterungen für bestimmte Anwendungsbereiche (z. B. Software-Dokumentation, Maschinenbau), wodurch der Elementvorrat anpassbar ist.

Zentrale Konzepte von DITA sind Wiederverwendung und Variabilität. Inhalte können mithilfe von content references (conref) und Schlüsselreferenzen (keyref) mehrfach genutzt werden, ohne sie zu duplizieren. Eine Änderung an der Ursprungsstelle aktualisiert dabei alle eingebundenen Stellen – das erhöht die Konsistenz und reduziert Pflegeaufwand. Über Profilierung (bedingte Inhalte) lassen sich Varianten für unterschiedliche Zielgruppen oder Produktversionen steuern: Bestimmte Textabschnitte werden mit Attributen (z. B. audience oder product) gekennzeichnet und durch eine Filterdatei (DITAVAL) für bestimmte Ausgaben ein- oder ausgeblendet. Metadaten und Taxonomien ergänzen DITA um kontextuelle Informationen: Sie klassifizieren Topics (etwa nach Produkt, Version, Zielgruppe) und steuern ebenfalls die Ausgabe oder Auffindbarkeit von Informationen.

Als Ausgabekanäle unterstützt DITA vielfältige Formate. Häufig eingesetzt werden HTML5 (z. B. für Web-Help oder Knowledge-Base) und PDF (für druckbare Handbücher). Weitere Formate wie EPUB, Markdown oder XML-Varianten sind über Erweiterungen ebenfalls möglich. Die eigentliche Umwandlung der Inhalte übernimmt das DITA Open Toolkit (DITA-OT) – ein Build-Werkzeug, das DITA-Quelltexte mithilfe vordefinierter oder angepasster Stylesheets in das gewünschte Zielformat publiziert. Dieses Automatisierungswerkzeug sorgt dafür, dass Publikationen konsistent und effizient erzeugt werden können.

Vorteile von DITA: Durch die modulare Anlage der Informationen erreichen Sie eine hohe Konsistenz – identische Inhalte werden zentral gepflegt und wiederverwendet, was widersprüchliche Dokumentation verhindert. Die Skalierbarkeit von Dokumentationsprojekten steigt, da Teams parallel an verschiedenen Topics arbeiten können und Inhalte via Maps flexibel zusammengestellt werden. Übersetzungen profitieren von DITA, weil wiederverwendete Textbausteine nur einmal übersetzt werden müssen und das XML-Format gängige Translation-Memory-Systeme optimal unterstützt. Auch Compliance-Anforderungen lassen sich besser erfüllen: Einheitliche Strukturen und zentrale Updates stellen sicher, dass z. B. Sicherheitshinweise überall korrekt und aktuell sind. Schließlich erleichtert DITA die Automatisierung der Dokumenterstellung – von regelmäßigen Veröffentlichungen in verschiedenen Formaten bis hin zu Integrationen in Continuous-Integration-Buildprozesse.

Was ist das Lernziel

Diese eintägige Schulung hat das Ziel, Ihnen praxisnah den Einstieg in DITA mit Adobe FrameMaker zu ermöglichen. Nach der Schulung sind Sie in der Lage:

• eine einfache DITA-Informationsarchitektur aufzubauen – mit modularen Topics und einer Map als Strukturübersicht.
• Inhalte wiederverwendbar zu erstellen, z. B. durch Einbindung von Content References (conref) und Schlüsselreferenzen (keyref) in Ihren Topics.
• Varianten zu steuern, indem Sie Profilierungsattribute vergeben und eine DITAVAL-Datei zur Filterung konfigurieren.
• in Adobe FrameMaker eine Publikation nach HTML5 und PDF aufzusetzen, das DITA Open Toolkit anzubinden und eventuelle Build-Fehler zu interpretieren.
• Metadaten effektiv einzusetzen, um Inhalte zu klassifizieren und die Ausgabe zu steuern (z. B. Zielgruppe, Produktversion als Attribut).
• Inhalte in FrameMaker strukturiert zu bearbeiten – mit dem Elementkatalog, dem Attribut-Editor und der Strukturansicht – und so valide DITA-Dokumente zu erstellen.

Am Ende des Kurses haben Sie ein kleines Demo-Projekt erarbeitet, das alle besprochenen Techniken vereint. Dieses Beispielprojekt (bestehend aus mehreren Topics und einer Map) wird im Kursverlauf so entwickelt, dass es zum Abschluss fehlerfrei nach HTML5 und PDF publiziert werden kann. Es dient Ihnen anschließend als Referenz und Ausgangspunkt für eigene DITA-Projekte.

Agenda der Schulung

Die Schulung findet live online von ca. 09:00 bis 17:00 Uhr statt (inklusive Pausen). Die folgende Agenda zeigt den typischen Ablauf des Kurstages:

Format-Legende: Vortrag = Dozentengeführter Theorieteil, Demo = Live-Vorführung durch den Trainer, Hands-on Übung = angeleitete praktische Übung der Teilnehmer, Q&A = Frage-und-Antwort-Runde.

Anmeldung & Organisatorisches

Die DITA-Schulung gibt es als geschlossenes Firmenseminar.

Eine Individualisierung der Agenda ist natürlich möglich.

Melden Sie sich bitte bei schulung@boddenberg.de.

Ausführliche Beschreibung der Schulung

Im Folgenden sind die einzelnen Module der Agenda näher beschrieben. Jedes Modul enthält konkrete Lernziele, die behandelten Inhalte, die praktische Übung (sofern zutreffend) sowie Hinweise zu häufigen Fehlern und den Transfer in den Arbeitsalltag.

Modul 1: Begrüßung, Ziele und Setup-Check (09:00–09:30)

Ziel: Sie kennen die Ziele und den Ablauf der Schulung und stellen sicher, dass Ihre technische Arbeitsumgebung für die DITA-Übungen korrekt eingerichtet ist.

Inhalte:
– Begrüßung und Vorstellungsrunde: Kurze Einführung des Trainers und der Teilnehmer. Überblick über Agenda und Lernziele des Tages.
– Technik-Check: Überprüfung, ob Adobe FrameMaker (Structured) in aktueller Version installiert und startbereit ist. Der Arbeitsbereich „XML/DITA Authoring“ wird ausgewählt, damit alle benötigten Fenster (Elementkatalog, Strukturansicht etc.) sichtbar sind.
– DITA-OT Integration: Kontrolle, ob das DITA Open Toolkit lokal installiert und in FrameMaker konfiguriert ist (Prüfen der Publish-Einstellungen auf korrekten DITA-OT-Pfad).
– Projektordner bereitstellen: Einführung in das bereitgestellte Beispiel-Repository (Verzeichnisstruktur mit Unterordnern für /topics, /maps, /images, /snippets, /ditaval, /publishing). Die Teilnehmer öffnen das Beispielprojekt in FrameMaker.
– Fragen klären: Beantwortung erster Fragen zum Ablauf, Sicherstellen, dass alle Teilnehmer die Übungsunterlagen haben.

Praktische Übung: Gemeinsam mit dem Trainer führen Sie einen kurzen Systemtest durch. Sie öffnen in FrameMaker eine mitgelieferte Test-DITA-Map aus dem Projektordner und starten einen Probe-Publikationslauf (z. B. HTML5-Ausgabe im Publish-Panel). So wird überprüft, ob die FrameMaker-Umgebung und DITA-OT richtig zusammenarbeiten. Etwaige Fehlermeldungen beim Test-Build (z. B. fehlender Java Runtime oder falscher DITA-OT-Pfad) werden direkt erkannt und behoben. Dieses Setup-Checking stellt sicher, dass Sie für die folgenden Übungen gerüstet sind.

Häufige Fehler und Troubleshooting:
– DITA-OT nicht gefunden: FrameMaker meldet beim Publizieren, dass kein DITA-OT verfügbar ist. Lösung: DITA-OT Installation prüfen und den Pfad in FrameMaker Publish-Einstellungen korrekt setzen.
– Java-Laufzeitfehler: Der Build startet nicht, weil Java fehlt. Lösung: Installation einer aktuellen Java Runtime Environment (JRE), die vom DITA-OT benötigt wird.
– Framework-Fehler in FrameMaker: Beim Öffnen der DITA-Beispieldateien treten Validierungsfehler auf. Lösung: Sicherstellen, dass FrameMaker im strukturierten Modus mit dem DITA-Framework arbeitet (ggf. richtigen Dokumenttyp auswählen oder FrameMaker neu starten, wenn Plugins nicht geladen waren).

Transfer in den Arbeitsalltag: Dieses Modul zeigt, wie wichtig eine solide technische Einrichtung ist. Sie lernen, vor Projektbeginn stets einen Umgebungs-Check durchzuführen – von der Tool-Installation bis zur Beispielpublikation. Diese Routine lässt sich im Arbeitsalltag direkt anwenden, um Ausfallzeiten zu vermeiden. Ein korrekt konfiguriertes Setup bildet die Grundlage für effizientes Arbeiten mit DITA und verhindert Fehler, bevor sie im Produktionsprozess auftreten.

Modul 2: DITA-Grundlagen und Informationsarchitektur (09:30–10:30)

Ziel: Sie verstehen die grundlegenden Konzepte von DITA und können die Architektur einer Dokumentation in selbstständige Topic-Bausteine und Maps aufteilen.

Inhalte:
– Theoretische Einführung in DITA: Was sind Topics, Maps und Domains? Vorstellung der Informationsarten Konzept, Aufgabe (Task), Referenz und wofür sie jeweils eingesetzt werden. Erklärung des Darwin-Prinzips (Vererbung/Spezialisierung von Informationsmodellen).
– Informationsarchitektur planen: Wie analysiert man vorhandene Dokumentation und zerlegt sie in sinnvolle DITA-Topics? Best Practices zur Granularität: Wann erstelle ich ein neues Topic, was gehört zusammen?
– Topic-Typen in der Praxis: Beispiele, welche Inhalte in ein Concept-Topic vs. Task-Topic gehören. Vorstellung der typischen Topic-Struktur (Titel, kurze Einleitung, ggf. Abschnitt, bei Task: Schritte als nummerierte Schrittelemente, bei Reference: tabellarische Infos etc.).
– DITA-Map aufbauen: Funktionsweise von Maps zur Zusammenführung von Topics. Erläuterung von Themenreferenzen (<topicref> in der Map) und der hierarchischen Organisation (Kapitel, Unterkapitel).
– Verknüpfungen und Navigation: Wie werden Inhalte verlinkt? Überblick über XRefs (Querverweise) und Navigationslinks, die automatisch aus der Map-Struktur entstehen. Rolle von keys in der Map für spätere Wiederverwendung (Vorbereitung auf Modul 4).
– Domains und Spezialisierung: Erwähnung, dass DITA anpassbar ist (z. B. Software-Domain fügt Elemente für GUI-Beschreibung hinzu). Hinweis, dass der Kurs den Standardumfang nutzt, aber erweiterbare Konzepte existieren.

Praktische Übung (Demo): Der Trainer demonstriert live in FrameMaker, wie ein neues DITA-Topic angelegt wird. Es wird z. B. ein Concept-Topic “Willkommen bei DITA” erstellt: FrameMaker öffnet ein leeres Template im XML-Editor-Modus. Der Elementkatalog wird genutzt, um die erforderlichen Strukturelemente (Titel, Absatz, Abschnitt etc.) einzufügen. Am Beispiel wird gezeigt, wie im Attribut-Editor Metadaten wie Produktname oder Audience gesetzt werden können. Ebenso wird eine neue DITA-Map angelegt und die erstellten Topics darin als <topicref> verknüpft. Die Live-Demo veranschaulicht die Konzepte unmittelbar in der Authoring-Umgebung.

Häufige Fehler und Troubleshooting:
– Ungültige Topic-Struktur: Vergessene Pflichtfelder (z. B. <title> fehlt) führen zu Validierungsfehlern. Lösung: Nutzung der FrameMaker-Strukturansicht und Validierungsfunktion, um Fehlerstellen sofort zu erkennen.
– Falscher Topic-Typ: Inhaltlich passt ein Abschnitt nicht zum Topic-Typ (z. B. Prozedur in Concept-Topic). Lösung: Gegebenenfalls Topic-Typ wechseln oder Inhalt anpassen; Best Practices beachten.
– Verlinkungsfehler: Ein Topic wurde nicht in die Map aufgenommen, daher fehlt es in der Navigation. Lösung: Map-Struktur prüfen und Topic via <topicref> hinzufügen; anschließend erneut Publikation prüfen.

Transfer in den Arbeitsalltag: Sie erwerben ein methodisches Verständnis, Dokumentationen nach DITA-Grundsätzen zu strukturieren. Im Berufsalltag hilft Ihnen dieses Wissen, vorhandene Inhalte in modulare Topics zu überführen und eine saubere Informationsarchitektur zu entwickeln. Dies bildet die Basis, um konsistente und wartbare Dokumentationsbibliotheken aufzubauen. Die in diesem Modul vermittelten Konzepte stellen sicher, dass Sie ein neues Dokumentationsprojekt von Anfang an mit klarer Struktur planen können.

Modul 3: Topics & Maps in der Praxis (Übung 1) – 10:45–12:15

Ziel: Sie wenden die DITA-Grundlagen praktisch an, indem Sie selbst Topics verschiedener Informationstypen erstellen und in einer Map organisieren. Am Ende dieses Moduls haben Sie eine kleine hierarchische Sammlung von verknüpften Topics aufgebaut.

Inhalte:
– Anlegen von Topics: Sie erstellen unter Anleitung drei neue Topics in FrameMaker: ein Concept, ein Task und ein Reference-Topic. Dabei verwenden Sie die FrameMaker-Vorlagen für DITA, sodass Grundstruktur und erforderliche Elemente bereits vorhanden sind.
– Bearbeiten mit Struktur-Tools: Einsatz des Elementkatalogs zum Hinzufügen von Elementen (Überschriften, Listen, Schritte etc.). Nutzung des Attribut-Editors, um z. B. das audience-Attribut (Zielgruppe) oder otherprops für projektspezifische Kennzeichnungen zu setzen. Einblendung der Strukturansicht, um die hierarchische Baumdarstellung des Topics zu kontrollieren.
– Bilden einer DITA-Map: Sie legen eine neue DITA-Map im Ordner /maps an. Anschließend fügen Sie die erstellten Topics als Referenzen in die Map ein (per Drag-and-Drop oder über Insert > Topicref in FrameMaker). Sie ordnen die Topics in einer sinnvollen Hierarchie an (z. B. Concept als Einführung, Task als Anleitung, Reference als Anhang).
– Speichern und Validieren: Alle erstellten Dateien werden gespeichert. Mit FrameMakers integrierter Validierung prüfen Sie, ob die Topics DITA-konform sind und ob die Map auf alle referenzierten Topics zugreifen kann (keine Broken Links).

Praktische Übung: Dies ist eine Hands-on-Session. Sie führen die obigen Schritte selbst am Rechner aus, unterstützt durch den Trainer. Für jedes Topic gibt es Beispielinhalte als Anhaltspunkt (im Kursmaterial oder Foliensatz angegeben), die Sie eingeben können – z. B. einen kurzen Konzepttext, eine Schritt-für-Schritt-Anleitung und eine kleine Referenztabelle. Die Übung dauert etwa 60–75 Minuten, inklusive kurzer Abschnitte, in denen der Trainer Ergebnisse mit allen Teilnehmern bespricht. Ziel ist ein lauf- und validees mini DITA-Projekt, bestehend aus drei Topics und einer Map, das als Grundgerüst für weitere Übungen dient.

Häufige Fehler und Troubleshooting:
– Validierungsfehler: FrameMaker markiert Regelverstöße (z. B. falsche Elementverschachtelung). Lösung: Nutzen Sie die Rückmeldungen der Strukturansicht; korrigieren Sie die Reihenfolge oder Hierarchie der Elemente gemäß DITA-Regeln.
– Referenzierungsfehler in Map: Rote Fragezeichen in der Map zeigen an, dass ein Topic-Pfad nicht gefunden wird. Lösung: Pfad der Topic-Datei prüfen (richtiger Dateiname, Verzeichnis) und Eintrag in der Map ggf. korrigieren.
– Umlaute/Encoding-Probleme: Falls Sonderzeichen im Inhalt falsch dargestellt werden, liegt ein Encoding-Problem vor. Lösung: Sicherstellen, dass alle DITA-Dateien in UTF-8 gespeichert sind (FrameMaker erledigt dies normalerweise automatisch für XML-Dateien).

Transfer in den Arbeitsalltag: Nach dieser Übung wissen Sie, wie man praktisch mit DITA in FrameMaker arbeitet. Sie haben gelernt, ein neues Dokumentationsprojekt anzulegen und strukturierte Inhalte zu verfassen. Diese Erfahrung können Sie direkt übertragen, um in Ihrem eigenen Arbeitsumfeld erste DITA-Projekte umzusetzen – etwa indem Sie ein kleines Handbuch mit Concept/Task/Reference-Modell aufbauen. Durch das praktische Tun gewinnen Sie Sicherheit im Umgang mit den Werkzeugen (Elementkatalog, Strukturansicht), was die Einarbeitung in zukünftige Projekte deutlich beschleunigt.

Modul 4: Wiederverwendung: conref und keyref (Übung 2) – 13:15–14:15

Ziel: Sie erlernen Techniken zur Inhaltswiederverwendung in DITA. Nach diesem Modul können Sie redundante Informationen vermeiden, indem Sie Inhalte als Schnipsel zentral pflegen und in mehreren Topics oder Maps referenzieren.

Inhalte:
– Einführung in Wiederverwendung: Warum Wiederverwendung? Vorteile für Konsistenz und Pflegeaufwand werden rekapituliert. Vergleich von Copy-Paste vs. Referenzierung – DITA-Ansatz vermeidet Dubletten.
– Content Reference (conref): Funktionsweise von conref erläutert: Ein Element in einem Topic kann seinen Inhalt aus einem anderen Topic beziehen. Syntax und Aufbau (Attribut conref mit URI auf Quell-Topic und ID des Elements). Beispiel: Eine standardisierte Warnung wird einmal in einem Snippet-Topic definiert und per conref in alle Task-Topics eingebunden, die diese Warnung benötigen.
– Key-basierte Referenzen: Vorstellung des Konzepts keyref: Anstatt direkt auf eine Dateipfad-ID zu verlinken, wird ein Key benutzt. In der DITA-Map wird ein Schlüsselname einer Zielressource (Topic oder Element) zugeordnet. Im Text referenziert man dann nur den Key. Vorteil: Die Zielreferenz kann zentral in der Map ausgetauscht oder pro Map variiert werden, ohne die Topics selbst zu ändern.
– FrameMaker-Unterstützung: Vorführen, wie FrameMaker conrefs und keyrefs einfügt. (z. B. über Insert Element > Content Reference oder Kopieren/Einfügen als Referenz). Hinweise zur Nutzung des Resource Manager oder Elementkatalogs für Referenzen.
– Best Practices: Sinnvolle Granularität für Snippets (nicht zu klein schneiden, um Kontextverlust zu vermeiden). Konventionen für IDs und Keys, damit Referenzen stabil bleiben. Dokumentation der wiederverwendeten Bausteine (z. B. in einem Snippet-Übersichtsdokument).

Praktische Übung: In dieser Übung (ca. 45–60 Minuten) erstellen Sie zunächst ein Snippet-Topic (z. B. warnungen.dita), das Beispieltexte enthält, die mehrfach benötigt werden (etwa Warnhinweise, firmenspezifische Haftungsausschlüsse oder wiederkehrende Einleitungen). Anschließend binden Sie dieses Snippet in andere Topics ein: Sie ersetzen z. B. in zwei Ihrer bestehenden Topics einen zuvor duplizierten Abschnitt durch einen conref, der auf das Snippet-Topic verweist. Zudem definieren Sie in Ihrer DITA-Map einen Key für das Snippet (z. B. warnung-standard) und verwenden alternativ an einer dritten Stelle einen <xref keyref=“warnung-standard“>, um auf denselben Inhalt zu verweisen. Sie beobachten im FrameMaker-XML-Ansicht, wie referenzierte Inhalte grau hinterlegt dargestellt werden (als Hinweis, dass der Text nicht direkt bearbeitet, sondern aus einer Quelle gezogen wird).

Häufige Fehler und Troubleshooting:
– Broken conref: Ein Content Reference zeigt ins Leere (rotes Kreuz-Symbol in FrameMaker). Lösung: Prüfen, ob die ID des Quell-Elements stimmt und die Quell-Datei in der Map oder im selben Ordner verfügbar ist. Gegebenenfalls Pfad oder ID korrigieren.
– Nicht aufgelöster keyref: Im ausgegebenen Dokument erscheint ein Platzhalter statt des Inhalts. Lösung: Sicherstellen, dass der Key-Name korrekt geschrieben ist und in der Map ein <keydef> mit diesem Namen existiert, der auf die richtige Ressource zeigt. Keys müssen zudem innerhalb des Gültigkeitsbereichs (Scope) der Map definiert sein.
– Editieren von referenziertem Text: Teilnehmer versuchen, grauen (referenzierten) Text direkt zu ändern. Lösung: Klarstellen, dass die Änderung im Quell-Topic erfolgen muss. FrameMaker bietet Funktion Edit Reference, um zur Quelle zu springen.

Transfer in den Arbeitsalltag: Die erlernten Wiederverwendungsfunktionen helfen Ihnen, Dubletten in Ihrer Dokumentation zu eliminieren. Im Alltag können Sie z. B. standardisierte Module (Sicherheitsrichtlinien, technische Daten, sich wiederholende Schritte) als einzelne Topics verfassen und überall referenzieren, wo sie gebraucht werden. Änderungen an zentraler Stelle aktualisieren automatisch alle Publikationen – das verbessert die Qualität und Konsistenz Ihrer Dokumentation und reduziert den Übersetzungsaufwand. Sie legen mit diesen Techniken den Grundstein für effizientes Content-Management, was gerade in großen Dokumentationsprojekten enorme Vorteile bringt.

Modul 5: Profilierung & Metadaten (Übung 3) – 14:30–15:30

Ziel: Sie lernen, Inhalte für unterschiedliche Zielgruppen oder Varianten zuzuschneiden, ohne separate Dokumente zu schreiben. Nach diesem Modul beherrschen Sie die Profilsteuerung von Inhalten mittels Attributen und DITAVAL sowie den sinnvollen Einsatz von Metadaten.

Inhalte:
– Varianten in der Dokumentation: Typische Anwendungsfälle für Profilierung (z. B. „Benutzer“ vs. „Administrator“ Handbuch, Produkt A vs. Produkt B Unterschiede). Erläuterung, wie DITA es ermöglicht, variable Inhalte in einem Topic unterzubringen.
– Profilierungsattribute: Vorstellung der standardmäßigen DITA-Attribute wie audience (Zielgruppe), product, platform, props etc. Diese werden genutzt, um bestimmte Inhaltselemente zu markieren. Beispiel: Ein Absatz erhält das Attribut product=“ProfiEdition“, damit er nur in der Doku der Profi-Edition erscheint.
– DITAVAL-Dateien: Funktionsweise von DITAVAL erläutern: Eine .ditaval-Datei listet Filterregeln auf (bestimmte Attributwerte einschließen oder ausschließen). Sie steuert den Build-Prozess, sodass gefilterte Inhalte in der Ausgabe weggelassen oder gekennzeichnet (z. B. mit einem Flag-Icon) werden.
– Anwenden der Profile im Tool: Demonstration im FrameMaker Publish-Panel, wie man eine DITAVAL-Datei der Publikation zuweist. Erläuterung der Conditional Text Ansicht in FrameMaker: gefilterte Inhalte ausblenden/einblenden zur Kontrolle.
– Metadaten-Verwendung: Neben Profilierungsattributen werden allgemeine Metadaten besprochen. Beispielsweise das <author>-Element, <category>/Taxonomie-Einträge in Maps oder benutzerdefinierte Metadata in <prolog>. Diese helfen bei Organisation und Wiederauffindbarkeit von Topics und können ebenfalls für Ausgabesteuerung (z. B. Indexerstellung, PDF-Deckblatt) genutzt werden.
– Best Practices: Keine Überfrachtung der Topics mit zu vielen Bedingungsattributen (Übersichtlichkeit wahren). Dokumentation der verwendeten Attribute/Werte in einem Variantenkonzept. Konsistente Anwendung der Metadaten (z. B. einheitliche Begriffe für Zielgruppen festlegen).

Praktische Übung: In Übung 3 (ca. 45 Minuten) statten Sie Ihre vorhandenen Topics mit Profilierungsmarkierungen aus. Sie erhalten ein Szenario: Bestimmte Abschnitte Ihres Demo-Projekts sollen nur für eine definierte Zielgruppe erscheinen (etwa Anwender vs. Administrator). Sie fügen dafür in einem Topic zwei alternative Absätze ein und vergeben je ein audience-Attribut (user bzw. admin). Anschließend erstellen Sie mit Anleitung eine DITAVAL-Datei (z. B. filter_admin.ditaval), in der Sie festlegen, dass audience=user ausgeblendet wird (für die Administrator-Doku). Im FrameMaker Publish-Panel wählen Sie diese DITAVAL-Datei aus und publizieren eine HTML5-Vorschau. Sie beobachten, dass die für Anwender bestimmten Absätze nun in der Ausgabe fehlen, während die Admin-Inhalte sichtbar sind. Zusätzlich probieren Sie die umgekehrte Filterung (zweite DITAVAL für Nutzersicht). Abschließend werden Metadaten geprüft: Sie fügen etwa im <prolog> der Topics einen Autorennamen und eine Produktversion ein, um den Nutzen dieser Angaben in einer PDF-Ausgabe (z. B. automatischer Titelblatt-Eintrag) zu demonstrieren.

Häufige Fehler und Troubleshooting:
– Inhalt versehentlich ausgeblendet: Nach Anwendung eines Filters fehlen unerwartet Inhalte. Lösung: DITAVAL-Regeln überprüfen – möglicherweise wurde ein Attributwert falsch geschrieben oder es fehlen Include-Regeln für eigentlich benötigte Inhalte. Immer nur gewünschte Werte ausschließen (Exclude) und mit Include arbeiten, um Klarheit zu behalten.
– Profilmarkierung nicht erkannt: Ein Attribut greift nicht, z. B. schreibt DITAVAL Logwarnungen „Attribut X unbekannt“. Lösung: Stellen Sie sicher, dass Sie standardkonforme Attributnamen nutzen (Tippfehler korrigieren) und dass die Attributwerte exakt mit denen in der DITAVAL-Datei übereinstimmen (Groß-/Kleinschreibung beachten).
– Metadaten ohne Effekt: Eingetragene Metadaten (z. B. <author>) erscheinen nicht sichtbar. Lösung: Verstehen, dass viele Metadaten nicht direkt im Inhalt erscheinen, sondern für Prozesse/Sortierung/Filterung genutzt werden. In FrameMaker können Sie z. B. im PDF-Template einstellen, ob der Autor auf dem Deckblatt gedruckt wird.

Transfer in den Arbeitsalltag: Mit Profilierungs-Techniken können Sie variantenreiche Dokumentation effizient steuern. Im Alltag ersparen Sie sich separate Dokumente für jede Zielgruppe oder Produktversion – eine einzige Quellbasis mit Attributen und Filterdefinitionen reicht aus. Das senkt den Pflegeaufwand und stellt sicher, dass alle Varianten auf dem gleichen Informationsstand sind. Metadaten helfen Ihnen zudem, Inhalte unternehmensweit konsistent zu klassifizieren (z. B. immer dieselben Produktnamen oder Modul-Bezeichnungen zu verwenden) und erleichtern Compliance-Aufgaben, da sich Berichte oder Auszüge nach bestimmten Kriterien (etwa alle sicherheitsrelevanten Topics) erzeugen lassen. Insgesamt lernen Sie, Inhalte zielgruppengerecht aufzubereiten, ohne die Vorteile der Wiederverwendung aufzugeben.

Modul 6: Publikation mit FrameMaker und DITA-OT (Übung 4) – 15:45–16:30

Ziel: Sie können DITA-Inhalte eigenständig in gängige Ausgabeformate (HTML5, PDF) publizieren. Nach dem Modul wissen Sie, wie man in FrameMaker das Publishing konfiguriert, den Build-Prozess anstößt und auftretende Fehler analysiert sowie behebt.

Inhalte:
– FrameMaker Publish-Panel: Vorstellung des Publish-Bedienfelds in FrameMaker. Sie sehen, wie man Ausgabeprofile auswählt oder neu anlegt (z. B. für HTML5 mit bestimmtem Template, für PDF mit Corporate-Design-Vorgaben). Erklärung der wichtigsten Optionen: Auswahl der DITA-Map als Wurzel für den Output, Zuweisung des DITA-OT-Pfads, Wahl der Ausgabeformate, Verknüpfen einer DITAVAL-Datei für Filter, Festlegen von Ausgabeordnern.
– Publikationslauf ausführen: Schritt-für-Schritt-Demonstration, wie ein HTML5-Output erzeugt wird. Hinweise, dass FrameMaker im Hintergrund das DITA-OT nutzt und temporäre Dateien anlegt. Vorstellung des Build-Logs (Protokoll), das während der Konvertierung erzeugt wird, und wie man es in FrameMaker einsehen kann.
– Typische Fehlerbilder: Besprechung häufiger Fehler beim Publizieren: z. B. ein Topic ohne <title> führt zu Build Warning, fehlende Grafikdateien erzeugen Fehler, veraltete DITA-OT-Versionen können inkompatibel sein. Auch Stil-Probleme werden erwähnt: z. B. wenn das PDF-Layout nicht wie gewünscht aussieht – Hinweis, dass hierfür Stylesheets oder Framemaker Templates angepasst werden müssen.
– PDF-Konfiguration: Einblick in die PDF-Erstellung: Nutzung von FrameMakers integrierter PDF-Engine vs. DITA-OT PDF (via XSL-FO oder PDF5-ML Plugin). In diesem Kurs wird das PDF5-ML Standardtemplate genutzt (oder Framemaker-eigene Templates), und es wird gezeigt, wo man z. B. das Firmenlogo oder Farben anpassen könnte (Details dazu als Verweis auf weiterführende Schritte, da dies eintägigen Rahmen sprengt).
– Mehrfachausgabe & Automation: Erwähnung, dass man mit FrameMaker auch mehrere Formate in einem Rutsch erzeugen kann (Publish Presets) und dass der Prozess mit Skripten oder einem Build-Server automatisiert werden kann – als Ausblick für fortgeschrittene Anwendung.

Praktische Übung: Im letzten Hands-on-Schritt publizieren Sie Ihr eigenes Kurs-Demoprojekt. Sie nutzen das FrameMaker Publish-Panel, um nacheinander folgende Ausgaben zu erzeugen: HTML5 (Web-Help) und PDF. Dazu wählen Sie die vorbereiteten Ausgabeprofile aus, die im Projektordner (/publishing) bereitgestellt wurden. Sie starten den Build und beobachten den Fortschrittsdialog. Sollte ein Fehler auftreten (z. B. ein fehlendes Bild im PDF), nutzen Sie das Fehlerprotokoll, um die Ursache zu finden – der Trainer unterstützt bei der Interpretation kryptischer DITA-OT-Meldungen. Gemeinsam werden ein oder zwei typische Fehler provoziert (z. B. Entfernen einer benötigten ID, um zu sehen, wie der Build darauf reagiert), um den Umgang mit dem Log zu üben. Am Ende halten Sie eine lauffähige HTML5-Ausgabe in Ihrem Browser bereit und ein geöffnetes PDF-Dokument, die beide Ihr erstelltes Inhaltsmodul repräsentieren.

Häufige Fehler und Troubleshooting:
– Build bricht ab: Die Publikation stoppt mit einer Fehlermeldung. Lösung: Im Log nach Fehlereinträgen suchen – häufig genannt werden die betroffene Datei und Zeilennummer. Fehler gezielt beheben (z. B. fehlendes <title> ergänzen, ungültiges Zeichen entfernen) und Build erneut starten.
– Bilder fehlen: In der HTML5-Ausgabe sind Platzhalter statt Bilder. Lösung: Pfade und Dateinamen der Grafiken prüfen; sicherstellen, dass im Output-Ordner die Bilder kopiert wurden. Ggf. in der DITA-Map <resourceid> für einen Bildordner verwenden oder FrameMaker-Einstellung Grafiken einbetten aktivieren.
– Formatierung stimmt nicht: PDF hat unerwartete Layoutprobleme. Lösung: Verstehen, dass das Standardlayout verwendet wurde – für CI-gerechtes Design müssten eigene Stylesheets oder Templates eingerichtet werden. (Dieser Punkt wird als Hinweis gegeben, Detailanpassung ist außerhalb des Grundkurs-Fokus.)

Transfer in den Arbeitsalltag: Sie sind nun imstande, selbstständig Publikationen durchzuführen. Dies bedeutet, dass Sie nach dem Autorieren nicht mehr auf externe Spezialisten angewiesen sind, um ein Handbuch zu erzeugen – Sie können direkt in FrameMaker ein publikationsfähiges Ergebnis erzeugen. Das Wissen um Logs und Fehlermeldungen versetzt Sie in die Lage, Probleme im Publikationsprozess eigenständig zu diagnostizieren. Langfristig können Sie Ihren Publikationsworkflow weiter optimieren: z. B. Integration in Build-Pipelines (Continuous Integration), um Dokumentation automatisch bei Release-Wechseln zu generieren. Mit den Grundkenntnissen aus dieser Schulung legen Sie den Grundstein, um auch erweiterte Einstellungen (wie eigene PDF-Designs oder verschiedene HTML5-Skins) später umzusetzen und somit Output vorlagenkonform an das Unternehmensdesign (CI) anzupassen.

Modul 7: Review, Abschluss-Checkliste und nächste Schritte (16:30–17:00)

Ziel: Sie frischen die gelernten Inhalte nochmals auf, überprüfen das entstandene Beispielprojekt auf Vollständigkeit und Qualität und wissen, wie es nach der Schulung weitergehen kann, um DITA erfolgreich im eigenen Umfeld zu etablieren.

Inhalte:
– Zusammenfassung und Wiederholung: Kurzer Rückblick auf alle Module – Was ist DITA, Aufbau der Topics, Wiederverwendung, Profilierung, Publikation. Offene Fragen aus den vorigen Sessions werden geklärt.
– Quiz: Der Trainer stellt 5–8 Quizfragen zu Kernbegriffen und Schritten (z. B. „Wofür steht die Abkürzung conref?“, „Wie blenden Sie in DITA Inhalte für eine bestimmte Zielgruppe aus?“). Die Teilnehmer beantworten interaktiv, um das Gelernte zu verfestigen.
– Abschluss-Checkliste: Gemeinsam wird das erstellte Demo-Projekt anhand einer Checkliste geprüft:

• Sind alle Topics mit Titeln und korrekter Struktur versehen? Baut das Projekt fehlerfrei nach HTML5 und PDF?
• Funktionieren die conrefs und keyrefs? (Keine ungültigen Referenzen sichtbar.)
• Greift die Profilierung wie erwartet? (In der gefilterten Ausgabe erscheinen nur die richtigen Inhalte.)
• Sind wichtige Metadaten gepflegt (Autor, Datum, Produktversion) und ist die Map-Struktur logisch und vollständig?

Diese Überprüfung zeigt, worauf in echten Projekten vor Publikationsfreigabe zu achten ist (Qualitätssicherung).

• Feedbackrunde: Die Teilnehmer haben Gelegenheit, Rückmeldungen zum Kurs zu geben und letzte Verständnisfragen zu stellen.
• Empfehlungen & nächste Schritte: Ausblick, wie es nach dem Training weitergeht. Vorschläge: Start eines Pilotprojekts im eigenen Unternehmen, um DITA im kleinen Umfang auszuprobieren. Erstellung eines unternehmensspezifischen Style Guides für die Verwendung von DITA (z. B. definieren von erlaubten Tags, Schreibstil, Metadata-Richtlinien). Anpassung der Ausgabeprofile ans Corporate Design (CI), z. B. durch eigene PDF-Templates mit Firmenlogo oder Anpassung des HTML5-Skins an die Unternehmenswebsite. Außerdem der Tipp, DITA in bestehende Prozesse einzubinden, etwa durch automatisierte Builds in einer Continuous-Integration-Umgebung (damit Dokumentation z. B. bei Software-Releases automatisch generiert wird). Abschließend werden weiterführende Ressourcen genannt (Literatur, Foren, evtl. Aufbauschulungen).

Häufige Fehler und Troubleshooting: (in diesem Modul entfallen klassische Fehler – stattdessen liegt der Fokus auf der Überprüfung und Anwendung des Gelernten; eventuelle Unklarheiten aus Übungen werden hier bereinigt.)

Transfer in den Arbeitsalltag: Dieses Abschlussmodul erleichtert den Übergang von der Theorie in die Praxis. Durch die Checkliste und die Nachbesprechung erhalten Sie ein klares Bild, worauf Sie bei realen DITA-Projekten achten sollten – von Qualitätssicherung (Validierung, Review-Prozesse, Terminologieeinhaltung) bis Projektplanung (Pilotphasen, schrittweise Einführung im Team). Die vorgeschlagenen nächsten Schritte unterstützen Sie dabei, DITA nachhaltig zu implementieren: Indem Sie zunächst klein anfangen und Erfolge intern präsentieren, schaffen Sie Akzeptanz. Mit einem definierten Style Guide und klaren Prozessen (etwa für Versionierung mit Git oder Review-Workflows) stellen Sie die Governance Ihrer technischen Dokumentation sicher. Schließlich wird deutlich, dass DITA kein einmaliges Projekt, sondern ein fortlaufender Verbesserungsprozess ist – doch mit dem Rüstzeug aus diesem Training sind Sie bestens vorbereitet, diesen Prozess in Ihrem Unternehmen lösungsorientiert und erfolgreich zu gestalten.