DITA in der Softwaredokumentation

1. Einleitung: DITA in der Softwaredokumentation

Softwareprojekte werden immer komplexer und agiler – entsprechend steigen die Anforderungen an die Technische Dokumentation. DITA (Darwin Information Typing Architecture) hat sich in diesem Umfeld als moderner XML-Standard bewährt. Mit DITA lassen sich Dokumentationsinhalte modularisieren, wiederverwenden und effizient für verschiedene Ausgabeformate aufbereiten. Gerade in Softwareprojekten bietet DITA großen Nutzen: Skalierbarkeit für wachsende Dokumentationsumfänge, konsistente Terminologie und Struktur über alle Publikationen hinweg, hohe Wiederverwendung (Reuse) von Inhalten sowie erhebliche Übersetzungseinsparungen durch Single-Source-Publishing.

Typische Artefakte in der Softwaredokumentation sind vielfältig und können alle mit DITA abgebildet werden:

• Benutzerhandbuch: Umfangreiche Anleitung für Endanwender, oft als PDF oder HTML-Handbuch bereitgestellt.
• Online-Hilfe: Webbasierte oder lokale Dokumentation, die dem Nutzer kontextsensitive Hilfetexte anbietet (z. B. über ein Hilfecenter oder Wiki).
• API-Dokumentation: Technische Referenz für Entwickler, z. B. Dokumentation von REST-APIs oder SDKs, inkl. Endpunkt-Beschreibungen und Code-Beispielen.
• Release-Notes: Änderungsprotokolle zu jeder Version der Software mit Auflistung neuer Features, Verbesserungen und behobener Fehler.
• In-App-Hilfe: Kontextsensitiv direkt in die Anwendung integrierte Hilfe (z. B. per F1-Taste), die dem Nutzer genau die zum aktuellen UI-Element passenden Informationen anzeigt.

Herausforderungen in der klassischen Dokumentation (etwa mit Textverarbeitung oder unstrukturiertem Authoring) können durch DITA gezielt adressiert werden. Die folgende Gegenüberstellung zeigt typische Probleme und die DITA-Lösungen:

Herausforderung (klassisch)	DITA-Ansatz (Lösung)
Redundante Inhalte – gleiche Texte in mehreren Handbüchern oder Varianten werden mehrfach erstellt und gepflegt.	Modulares Single-Source – Inhalt einmal schreiben und per Conref (Inhaltsreferenz) oder Topic-Include an vielen Stellen einbinden, statt Copy-Paste.
Inkonsistente Struktur & Terminologie – jeder Autor formatiert und formuliert anders, kein einheitlicher Aufbau.	Standardisierte Topics & Styleguide – DITA gibt eine einheitliche Topic-Struktur (z. B. Task, Concept, Reference) vor. Klare Richtlinien sorgen für konsistente Begrifflichkeit und Aufbau.
Hoher manueller Formatierungsaufwand – Zeitverlust durch Layout in Word, Fehler bei der Ausgabeerstellung.	Trennung von Inhalt und Layout – Autoren fokussieren auf Inhalte, das Layout wird zentral über Templates/Stylesheets im DITA-OT gesteuert. Weniger Fehler, schneller zum finalen Dokument.
Aufwändige Publikation & Übersetzung – jede Variante erfordert eigenes Dokument, Übersetzungen verdoppeln den Aufwand.	Automatisierte Publikationspipeline – DITA generiert aus einer Quelle viele Ausgabeformate und Sprachen. Wiederverwendung reduziert den Übersetzungsumfang (gleiche Segmente nur einmal übersetzen).

Zusammengefasst ermöglicht DITA also skalierbare, konsistente Dokumentation in Softwareprojekten. Es erhöht die Übersetzungseffizienz (Standardformulierungen und wiederverwendete Bausteine müssen nur einmal übersetzt werden) und verkürzt die Time-to-Market für Dokumente. Im Ergebnis erhalten Nutzer aktuelle, einheitliche Handbücher und Hilfen – trotz schneller Software-Release-Zyklen. Im nächsten Abschnitt werden die DITA-Grundlagen vorgestellt, die für Softwareteams besonders relevant sind.

2. DITA-Grundlagen für Softwareteams

Ein Softwareteam, das DITA einführt, sollte die wesentlichen Konzepte des Standards verstehen. DITA ist ein XML-basiertes Framework, das spezielle Mechanismen für technische Dokumentation bereitstellt. Im Folgenden die wichtigsten Grundlagen:

Informationsmodell und Topic-Typen: DITA zerlegt die Dokumentation in modularisierte Themen (Topics). Jedes Topic behandelt ein abgegrenztes Informationsobjekt. Es gibt drei zentrale Topic-Typen: Task (Prozedur/Aufgabe mit Schrittanleitungen), Concept (Konzeptbeschreibung, z. B. Hintergrundwissen) und Reference (Referenzinformationen, z. B. API-Parameter oder Tabellen). Zusätzlich können spezialisierte Topic-Typen definiert werden, aber Task/Concept/Reference haben sich als Standard etabliert. Die Topics werden über DITA-Maps organisiert: Eine Map ist eine Sammlung von Verweisen auf Topics, hierüber wird die Struktur der Publikation (Inhaltsverzeichnis, Reihenfolge) festgelegt. Maps dienen auch als zentrale Stelle, um Variablen und Schlüssel (Keys) zu definieren. Mit Keys lassen sich Platzhalter für Namen, Pfade oder Werte setzen, die später kontextabhängig aufgelöst werden. Beispiel: Ein Schlüssel PRODUCT_NAME wird je nach Produktvariante unterschiedlich definiert und im Text überall konsistent ersetzt. Schließlich bietet DITA mit Conref (Content Reference) die Möglichkeit, Inhalt von einem Topic in ein anderes dynamisch einzufügen – ideal, um identische Textblöcke nur einmal vorzuhalten.

Wiederverwendung und Variantensteuerung: Einer der größten Pluspunkte von DITA ist die Wiederverwendung von Inhalt. Snippets oder Module – etwa ein Warnhinweis, eine häufige Schrittfolge oder ein Standardabschnitt – können als eigenes Topic oder Element erstellt und via Conref an beliebiger Stelle eingebunden werden. Änderungen am Ursprungstext propagieren sich automatisch an alle Verwendungen. Neben ganzen Topics können auch kleinere Elemente (Absätze, Tabellen, Listen) referenziert werden. Zusätzlich beherrscht DITA Profilierung (Conditional Processing): Über Attribut-Markierungen am Inhalt wird gesteuert, welche Textteile in welcher Variante sichtbar sind. Ein und dasselbe Topic kann z. B. Passagen enthalten, die nur für Administratoren bestimmt sind (Attribut audience=“admin“) oder nur auf Linux zutreffen (Attribut platform=“linux“). Beim Publizieren filtert man mittels Profilierungsprofil (DITA-OT Ditaval-Datei) die nicht relevanten Teile heraus. So entstehen aus einer Quellbasis verschiedene Ausgaben (z. B. Edition Standard vs. Pro, oder Benutzerdoku vs. Admin-Doku), ohne dass man separate Dokumente manuell pflegen muss.

Governance: Namenskonventionen, Struktur, Taxonomie: Damit ein DITA-Projekt mit vielen Topics übersichtlich bleibt, ist Governance gefragt – also verbindliche Regeln für die Organisation der Inhalte. Dazu zählen klare Namenskonventionen für Dateien und IDs (z. B. alles kleingeschrieben, Wörter durch Minus getrennt, Dateinamen sollen den Topic-Inhalt widerspiegeln), eine sinnvolle Ordnerstruktur im Repository (z. B. Ordner pro Modul, pro Publikationstyp oder nach Sprachversionen) sowie eine durchdachte Taxonomie. Letzteres bedeutet: Inhalte werden kategorisiert, etwa nach Produktbereichen, Funktionstypen oder Zielgruppen. Eine konsistente Taxonomie und Vergabe von Metadaten (wie Produktname, Version, Autor, Schlagwörter) erleichtert das Auffinden von Topics und die Wiederverwendung. Governance umfasst auch redaktionelle Richtlinien – z. B. welche Topic-Typen wann zu verwenden sind, wie Überschriften zu formulieren sind – um Einheitlichkeit sicherzustellen. Diese Regeln sollten in einem Redaktionsleitfaden festgehalten und allen Teammitgliedern bekannt sein.

Qualitätssicherung: DITA bringt von Haus aus eine formale Validierung mit: Da Topics XML-basiert nach definierten Schemas/DTDs sind, lassen sie sich automatisiert auf Strukturfehler prüfen. Ein Topic, dem z. B. eine erforderliche Überschrift oder ein </>Tag fehlt, wird vom Validator gemeldet. Darüber hinaus lassen sich Schematron-Regeln oder QA-Tools einsetzen, um stilistische und inhaltliche Qualität zu sichern (z. B. Terminologie, verbotene Formulierungen, Einhaltung des Stilguides). In der Praxis etabliert man einen Review-Prozess: Autoren geben neue oder geänderte Topics an Fachexperten oder Lektoren zur Prüfung. DITA erleichtert dies, da man einzelne Topics isoliert reviewen kann (z. B. als HTML-Preview oder in einem CCMS), statt immer das ganze Dokument versenden zu müssen. Versionierungswerkzeuge (Git, SVN) spielen ebenfalls eine Rolle: Sie ermöglichen Änderungsverfolgung und Vergleiche zwischen Versionen. Insgesamt sorgt DITA so dafür, dass inhaltliche Fehler, Strukturbrüche oder Widersprüche früh erkannt und behoben werden, bevor die Dokumentation veröffentlicht wird.

Übersetzung (Lokalisierung): Für mehrsprachige Software ist die Effizienz der Übersetzung ein kritischer Faktor. DITA punktet hier gleich mehrfach. Durch Wiederverwendung reduziert sich die zu übersetzende Wortmenge drastisch – ein wiederverwendeter Absatz muss nur einmal übersetzt werden, egal in wie vielen Handbüchern er auftaucht. Übersetzungstools (Translation-Memory-Systeme) erkennen dank identischer Segmentierung schnell, welche Sätze schon aus früheren Versionen oder anderen Handbüchern übersetzt wurden. Das erhöht Konsistenz und senkt Kosten. Zudem führt die klare Struktur und standardisierte Terminologie in DITA dazu, dass Übersetzer weniger Interpretationsspielraum haben – das verringert Fehler. Vor einer Lokalisierung sollte das Team allerdings die Inhalte übersetzungsfreundlich gestalten: Einheitliche Terminologie, keine kulturell spezifischen Anspielungen, kurze klare Sätze. DITA erzwingt zwar einfache Struktur, aber nicht automatisch einfachen Sprachstil – hier greift wieder die redaktionelle Richtlinie (ggf. kontrollierte Sprache). Technisch gesehen werden DITA-Inhalte meist via XLIFF oder ähnlichen Formaten an Übersetzungsdienstleister gegeben. Der Übersetzungsworkflow kann so integriert werden, dass neue oder geänderte Topics automatisch zur Übersetzung exportiert und nach Rücklauf wieder ins richtige Projekt einsortiert werden. Ergebnis: kürzere Durchlaufzeiten und bis zu zweistellige Prozent-Ersparnisse bei Übersetzungskosten im Vergleich zu unstrukturierten Dokumenten.

Publikation und Automation: Ein zentrales Element von DITA ist die automatische Publikation in verschiedene Formate. Das Open-Source-Werkzeug DITA-OT (DITA Open Toolkit) dient als Motor der Ausgabeerstellung. Es unterstützt out-of-the-box zahlreiche Formate, darunter HTML5 (für Web-Dokumentationen oder Help-Center), PDF (für klassische Handbücher), eclipsehelp/CHM (für kontextsensitive Hilfe in Anwendungen) und weitere (Markdown, EPUB, etc. via Plugins). In einem Softwaredokumentations-Projekt richtet man typischerweise eine Publikationspipeline ein: Zum Beispiel könnte bei jedem neuen Software-Release automatisch ein Skript angestoßen werden, das die entsprechende DITA-Map nimmt, das DITA-OT aufruft und HTML sowie PDF generiert. Diese Outputs werden dann entweder ins Produkt integriert (bei kontextsensitiver Hilfe) oder auf eine Doku-Website gestellt. Continuous Integration (CI) Systeme wie Jenkins oder Azure DevOps lassen sich nutzen, um den Vorgang zu automatisieren – z. B. nächtliche Builds der Dokumentation, sodass stets eine aktuelle Version zur Verfügung steht. Autoren profitieren davon, dass sie sich nicht mit den Einzelheiten der Formatierung aufhalten müssen: Layout und Design werden zentral mittels Stylesheets gesteuert. Änderungen am Corporate Design (Logos, Farben, Schriftarten) müssen nur an einer Stelle angepasst werden und fließen in alle Ausgaben ein. Insgesamt beschleunigt dies den Publikationsprozess enorm: Zeitspannen von mehreren Tagen manuellem Zusammenstellen und Formatieren lassen sich auf Minuten oder wenige Stunden reduzieren. Gleichzeitig erhöht sich die Zuverlässigkeit, da jeder Build reproduzierbar die gleichen Regeln anwendet – ein wichtiger Aspekt für Qualität und Compliance.

3. Informationsarchitektur & Taxonomie in Softwareprojekten

Bei der Anwendung von DITA in Softwaredokumentations-Projekten spielt die Informationsarchitektur eine entscheidende Rolle. Sie bestimmt, wie Inhalte strukturell organisiert, modularisiert und verschiedenen Varianten zugeordnet werden. Eine durchdachte Architektur bildet gewissermaßen das Rückgrat, damit DITA sein volles Potenzial entfalten kann. Wichtige Aspekte dabei sind:

Trennung von Produktvarianten, Editionen, Plattformen: Softwareprodukte existieren oft in Variationen – etwa Editionen (Basis vs. Premium), Bereitstellungsformen (Cloud-Service vs. On-Premises Installation) oder Plattformen (Windows, macOS, Linux). In der Dokumentation führt das klassisch zu getrennten Handbüchern mit viel Duplikattext. Mit DITA hingegen kann man eine einzige Quellbasis nutzen und Unterschiede gezielt aussteuern. So empfiehlt es sich, gemeinsame Funktionen in gemeinsamen Topics zu dokumentieren und nur tatsächlich unterschiedliche Features zu verzweigen. Profilierung hilft dabei enorm: Inhalte, die nur für eine Variante gelten, werden mit entsprechenden Attributen markiert. Beispielsweise könnte ein Absatz mit Attribut platform=“windows“ ausschließlich in der Windows-Doku erscheinen, während ein Linux-spezifischer Hinweis analog markiert ist. Die DITA-Map kann dann für jede Variante mit den passenden Filtereinstellungen publiziert werden. Auch getrennte Maps je Variante sind möglich (z. B. Handbuch_Cloud.ditamap vs. Handbuch_OnPrem.ditamap, die aber viele identische Topics referenzieren). Wichtig ist, von Anfang an klar zu definieren, welche Unterschiede vorkommen und wie sie abgebildet werden. Dadurch erreicht man, dass – zum Beispiel – 80% des Inhalts zwischen zwei Editionen identisch sind und gepflegt werden wie einer, während nur die restlichen 20% spezifisch und gefiltert sind. Die Dokumentation bleibt konsistent, aber dennoch zielgruppengerecht für jede Produktvariante.

Modularisierung entlang der Softwarearchitektur: Ein erfolgreiches Informationsmodell spiegelt oft die Architektur der Software wider. Das bedeutet, Dokumentationsmodule orientieren sich an Software-Modulen oder -Komponenten. Beispielsweise kann man für eine Anwendung mit verschiedenen Microservices oder Modulpaketen die DITA-Inhalte entsprechend gruppieren: Ein Ordner bzw. ein Kapitel pro Service/Modul, darin die zugehörigen Topics (Konzept-Themen, GUI-Beschreibungen, API-Referenzen, etc.). Diese Modularisierung erleichtert nicht nur den Überblick, sondern auch die Zuständigkeit im Team – Entwickler oder Fachexperten können gezielt an „ihrem“ Modul in der Dokumentation mitarbeiten. Zudem wird Wiederverwendung begünstigt: Gemeinsame Funktionen mehrerer Module (z. B. eine Standard-Login-Funktion) können als eigenes Topic abgelegt und in jedem Modul-Unterabschnitt referenziert werden, anstatt redundant beschrieben zu werden. Die DITA-Map einer Gesamtdoku referenziert dann die einzelnen Modul-Maps oder -Themen zu einem großen Ganzen. So entsteht eine skalierbare Struktur, die mit dem Softwareprodukt mitwächst. Neue Module? – einfach einen neuen Ordner mit Topics und einen Map-Eintrag hinzufügen, ohne die restliche Doku zu tangieren.

Mapping auf Entwicklungsartefakte: In agilen Softwareprojekten werden Anforderungen und Änderungen häufig über Tickets/User Stories in Tools wie JIRA, Azure DevOps oder ähnlichen Systemen verwaltet. Die Dokumentation kann hier anschließen: Eine gute Praxis ist es, Dokuartefakte mit Entwicklungsartefakten zu verknüpfen. Das kann auf verschiedene Weise geschehen. Beispielsweise kann jedes DITA-Topic ein Metadatenfeld „Requirement-ID“ oder „Ticket-Nummer“ tragen, um nachzuvollziehen, welche Anforderung es dokumentiert. Oder es werden pro User Story initial „Dokumentations-Tasks“ angelegt, die dann in DITA als Task-Topics umgesetzt werden. Einige Teams generieren sogar rudimentäre Topics automatisch aus Akzeptanzkriterien der Entwicklungsstories, welche die Redakteure dann ausformulieren. Durch solche Kopplungen verbessert sich die Nachvollziehbarkeit erheblich: Ein Qualitätsmanager kann etwa fragen, ob für Ticket XY auch die Doku angepasst wurde – und findet mittels ID-Verknüpfung sofort das entsprechende Topic. Ebenso kann man bei einem Dokumentationsabschnitt nachschauen, aus welcher Story oder welchem Change-Request er hervorgegangen ist. Für Compliance und Audit-Trails ist diese Rückverfolgbarkeit ein großer Gewinn. Die Informationsarchitektur sollte daher vorsehen, wo und wie solche Verknüpfungen erfolgen (im Dateinamen? in den Topic-Metadaten? via Linkliste in einer Map?). Idealerweise wird das integrativ gelöst, z. B. durch ein Content-Management-System oder Skripte, die DITA-Maps aus Ticketlisten erzeugen.

Versionierung über Releases und Lebenszyklen: Software lebt in Versionen. Major Releases, Minor Updates, Patches, langfristige LTS-Zweige – all das muss in der Doku abgebildet sein. Bei DITA gibt es zwei Hauptansätze: zum einen branching in der Versionsverwaltung (z. B. ein Git-Branch pro Release, in dem die DITA-Dateien ggf. angepasst werden), zum anderen conditional content über Profilierung (z. B. Attribute für Versionen). In vielen Fällen nutzt man eine Kombination. Beispielsweise könnte für Version 3.x ein Dokumentationszweig angelegt werden, während kleine Patches (3.1 vs 3.2) über bedingte Texte innerhalb der Topics gelöst werden. Wichtig ist eine klare Strategie: Autoren müssen wissen, wo sie Änderungen vornehmen, damit diese in die zukünftigen Versionen übernommen oder gezielt nicht übernommen werden. Ein gängiges Vorgehen ist „Forward-Propagation“ – Änderungen werden in der ältesten noch gepflegten Version gemacht und dann in neuere Versionen gemerged, um Konsistenz zu wahren. Kennzeichnend für DITA ist, dass es flexibel genug ist, um auch mehrere Versionen gleichzeitig in einer Publikation zu behandeln (etwa ein Hinweis „gilt ab Version 5.0“ als profilierter Text). Doch Vorsicht: Zu viel Versionslogik in einem Dokument kann die Leser überfordern. Daher kann es sinnvoll sein, getrennte Dokumente pro Hauptversion zu veröffentlichen (z. B. Admin Guide v1, Admin Guide v2), obwohl im Hintergrund vielleicht 80% der Topics identisch sind und aus derselben Quelle stammen. Die Informationsarchitektur muss diese Balance zwischen Wiederverwendung und Klarheit finden. Messgrößen wie die Anzahl paralleler Pflegelinien, die Frequenz von Releases und der Aufwand für Dokumentationsaktualisierung pro Release fließen in diese Planung ein.

Messbare Größen (KPIs) der Dokumentationsleistung: Zur Bewertung und Steuerung eines DITA-basierten Doku-Projekts werden oft Kennzahlen herangezogen. Einige wichtige Metriken sind:

• Wiederverwendungsquote: Sie gibt an, wie viel Prozent des Inhalts mehrfach genutzt werden. Man kann sie pro Release oder insgesamt messen (z. B. Anteil der Topics, die in mehr als einer Map vorkommen). Steigt diese Quote (z. B. von 30% auf 60%), spricht das für erfolgreiche Modularisierung und weniger Doppelarbeit.
• Time-to-Publish: Diese Zeitspanne vom Entwicklungsabschluss (Code Freeze) bis zur veröffentlichten Dokumentation soll möglichst gering sein. Mit DITA und Automatisierung lässt sich oft erreichen, dass Dokumentation parallel zur Software entsteht und praktisch zeitgleich veröffentlicht wird. Ein Team könnte z. B. die Publikationszeit von mehreren Wochen nach Release auf 2–3 Tage oder weniger reduzieren.
• Übersetzungsaufwand: Gemessen in zu übersetzenden Wörtern oder in Übersetzungskosten pro Release. Durch DITA sollten diese Werte pro Release tendenziell sinken, auch wenn insgesamt mehr Features dazukommen – eben weil neue Texte oft unter 100% stehen, während viele Sätze bereits übersetzt vorliegen. Eine Reduktion des Übersetzungsvolumens um beispielsweise 30% nach Einführung von DITA ist nicht unüblich.
• Fehlerdichte: Anzahl der Dokumentationsfehler oder -änderungsmitteilungen pro veröffentlichtem Umfang (z. B. Errata pro 100 Seiten). Strukturierte Inhalte und Validierung führen oft zu weniger inhaltlichen Fehlern (vergessene Updates, falsche Verweise). Ein Rückgang der gemeldeten Doku-Bugs um z. B. 50% nach Umstellung auf DITA wäre ein Erfolgskriterium.
• Review-Durchlaufzeiten: Wie lange brauchen Reviews und Freigaben der Dokumentation? Durch modulare Reviews (Thema für Thema) kann dieser Prozess parallelisiert werden. KPI ist hier z. B. die durchschnittliche Dauer einer Review-Runde oder die Anzahl Topics, die ein Reviewer pro Woche schafft. Verbesserungen zeigen sich etwa in schnellerer Feedback-Loop und weniger Iterationen, weil die Qualität initial höher ist.

All diese Kennzahlen erlauben der Projektleitung Technische Redaktion und anderen Stakeholdern (Produktmanagement, Qualitätssicherung) den Fortschritt messbar zu machen. Sie dienen auch dazu, Schwachstellen zu identifizieren (z. B. unerwartet niedrige Wiederverwendung könnte auf Redundanzen hinweisen, die man eliminieren kann) und den ROI von DITA zu belegen – etwa wenn Übersetzungskosten sinken und Publikationen schneller fertig sind, kann dies quantifiziert werden.

4. Fünf ausführliche Praxisbeispiele für erfolgreiche DITA-Nutzung

Nach den Grundlagen nun der Blick in die Praxis: In diesem Kapitel werden fünf Beispiele aus unterschiedlichen Bereichen der Softwaredokumentation vorgestellt. Jedes Beispiel beschreibt die Ausgangssituation, die Ziele des Projekts, die umgesetzte Lösung mit DITA (Struktur, Reuse-Mechanismen, Profilierung, Taxonomie), die eingesetzte Toolchain bzw. Automatisierung (inkl. DITA-OT) sowie erzielte Ergebnisse und Lessons Learned. Diese anonymisierten Fallstudien zeigen, wie DITA in realen Szenarien Mehrwert stiftet.

4.1 API-Dokumentation für eine Microservices-Plattform

Ausgangslage: Ein Softwareanbieter betreibt eine umfangreiche Microservices-Plattform mit dutzenden REST-APIs. Die API-Dokumentation war ursprünglich in verschiedenen Wiki-Seiten und manuellen PDF-Dokumenten verstreut. Entwickler fanden Informationen nur mühsam, und bei Updates wurden häufig Abschnitte vergessen. Zudem existierten mehrere API-Versionen parallel (v1, v2…), was die Dokumentation weiter aufspaltete. Das Doku-Team (3 Technical Writer) stand vor der Aufgabe, hunderte Endpunkte konsistent zu dokumentieren – inklusive Beschreibung der JSON-Schemata, Beispielanfragen und -antworten –, ohne in Copy-Paste-Orgie zu versinken.

Zielsetzung: Gesucht war eine Lösung, um die API-Dokumentation zu zentralisieren und eng mit den Entwicklungsartefakten (OpenAPI-Spezifikationen) zu koppeln. Hauptziele: Redundanzen eliminieren, konsistente Formatierung aller Endpunkt-Beschreibungen, Fähigkeit zur Versionsverzweigung (ältere API-Versionen sollen weiterhin verfügbar sein, aber klar gekennzeichnet) und einfache Übersetzbarkeit ins Englische, Deutsche und Japanische. Außerdem wollte man ein Entwicklerportal schaffen, in dem neben Referenzinformationen auch erklärende Texte (Konzepte, How-tos) integriert sind.

Lösung: Die Entscheidung fiel auf DITA als Backbone der neuen API-Doku. Zunächst wurden OpenAPI-Artefakte (Swagger-Definitionen der REST-APIs) genutzt, um Referenz-Topics zu generieren. Ein Konverter-Skript las die OpenAPI-JSON-Dateien jeder Microservice-API ein und erzeugte daraus DITA Reference Topics – pro Endpunkt ein Topic mit Beschreibung, Parameter- und Response-Tabellen. Diese Topics wurden automatisch mit dem entsprechenden Versionsattribut versehen (z. B. apiVersion=“v2″). Gleichzeitig erstellten die Technischen Redakteure manuell Concept-Topics für Überblicksthemen (z. B. „Was ist der Service XY? Wie authentifiziere ich mich?“) und Task-Topics mit Schritt-für-Schritt-Anleitungen (etwa „So integrieren Sie Service XY in Ihre Anwendung“). Die DITA-Content-Architektur gliederte sich pro Microservice: ein Ordner je Service, darin Unterordner nach Version. Wiederverwendung kam ins Spiel bei allgemeinen Abschnitten – z. B. galt ein Authentifizierungsverfahren für viele Services gleich. Solche Texte wurden als eigene Topics verfasst und via Conref in alle relevanten Endpunkt-Beschreibungen eingebunden. Ebenso wurden Fehlermeldungen, HTTP-Statuscode-Erklärungen etc. als Snippets zentral gepflegt. Für die Taxonomie wurden alle Services einer Kategorie (Finance-APIs, User-APIs, etc.) zugeordnet, was in Metadaten hinterlegt ist, damit das Portal entsprechende Filter anbieten kann.

Toolchain/Automatisierung: Adobe FrameMaker diente als Authoring-Tool für die manuelle Inhaltserstellung. Die automatisierte Erzeugung der Referenz-Topics aus OpenAPI lief über ein Python-Skript, das vom CI-System getriggert wurde, sobald Entwickler eine neue Swagger-Datei eincheckten. Die Publikationspipeline kombinierte alle Topics eines Service zu einer DITA-Map (pro Service und Version). Dann wurde das DITA-OT ausgeführt: Es generierte eine HTML5-Dokumentation mit einer eigenen Output-Facet je API-Version. Durch Keys und Variable-Einsetzungen konnte das Portal Versionsumschalter anzeigen (die hinterlegte Schlüssel in Links nutzten, um zwischen v1/v2 umzuschalten). PDF-Ausgaben wurden für interne Zwecke ebenfalls erzeugt (z. B. um sie Partnern bereitzustellen), mit einem PDF-Plugin des DITA-OT. Die gesamte Pipeline – von Quellsystem bis Deployment – war automatisiert im CI-Prozess integriert: Bei jedem Release der Software liefen Build-Jobs, die die aktuelle Dokumentation in drei Sprachen erzeugten und ins Developer-Portal deployten.

Ergebnisse: Die API-Dokumentation wurde durch diese DITA-Lösung deutlich effizienter und hochwertiger. Etwa 500 Endpunkte in über 50 Services konnten abgedeckt werden, ohne dass die Redakteure jeden einzeln von Grund auf schreiben mussten – rund 75% der reinen Referenzinhalte (Parameterlisten, Statuscodes etc.) wurden automatisiert generiert. Die Redakteure konzentrierten sich auf die verbleibenden ~25% erklärenden Inhalt (Konzepte, Anwendungsbeispiele). Wiederverwendung wurde intensiv genutzt: Gemeinsame Textelemente (z. B. ein identischer Sicherheitshinweis für alle Authentifizierungs-APIs) existieren nur einmal und fließen via Conref in über 20 Topics ein. Die Konsistenz stieg drastisch – alle Endpunkt-Beschreibungen folgen nun dem gleichen Aufbau, Begriffe werden einheitlich verwendet (Terminologie war hinterlegt und wurde beim Authoring beachtet). Die Time-to-Publish für eine neue API-Version verkürzte sich von zuvor mehreren Wochen (manuelles Schreiben & Layouten) auf < 1 Woche: Sobald Entwickler die Spezifikation fertig stellten, konnte binnen weniger Tage die aktualisierte Dokumentation publiziert werden, da viele Schritte automatisiert abliefen. In Zahlen: eine Major-Version v3 der APIs wurde mit nur 2 Redakteurstagen Dokumentationsarbeit komplett veröffentlicht, während v2 früher ~10 Tage benötigt hatte. Übersetzung: Durch die hohen Wiederverwendungsraten sank das zu übersetzende Textvolumen um ~30%. Das Team übersetzte die DITA-Topics zunächst ins Englische (Ausgangssprache war hier Japanisch) und ließ anschließend die Zweitsprache Deutsch via Translation-Memory-Service einpflegen. Dank identischer Segmente, die durch DITA-Vererbung entstanden, konnte der Übersetzer viele Sätze aus vorherigen Releases recyceln. Die resultierende mehrsprachige Doku im Entwicklerportal fand großen Anklang bei Nutzern – Zugriffsstatistiken zeigten eine 15% höhere Verweildauer, da neben reinen Referenzen nun auch How-to-Guides vorhanden waren.

Lessons Learned: Die Einführung von DITA in der API-Dokumentation zeigte, wie wichtig die Abstimmung zwischen Entwicklung und Redaktion ist. Ein zentrales Learning: Der Automatismus ist nur so gut wie die Quelle – man musste die Entwickler dazu bringen, die Swagger-Definitionen sorgfältig und mit genügend Beschreibungstext zu pflegen, damit die generierten DITA-Topics sinnvoll waren. Initial gab es hier Abstimmungsbedarf (Lesson: früh Entwickler ins Boot holen, damit Dokumentationsanforderungen schon bei der Code-Dokumentation bedacht werden). Außerdem lernte das Team, dass Vorlagen und Templates Gold wert sind: Es wurde ein standardisiertes Muster für API-Concept-Topics erstellt (inkl. Platz für Diagramme, Sequenzcharts etc.), was die Einheitlichkeit förderte. Ein unerwarteter Effekt war, dass durch DITA die Zusammenarbeit zwischen verteilten Doku-Teams (USA, Europa, Asien) einfacher wurde – alle arbeiteten im gleichen strukturierten Repository, was Überschneidungen reduzierte. Wichtig war abschließend die Erkenntnis, dass trotz Automatisierung redaktionelle Kontrolle nötig bleibt: Die Writers prüften stichprobenartig generierte Inhalte und verbesserten die Templating-Regeln iterativ (z. B. Formatierung von Beispiel-JSON). Somit verbindet die Lösung das Beste aus beiden Welten – Automation für Fleißarbeit, menschliche Qualitätssicherung für Verständlichkeit.

4.2 Kontextsensitive In-App-Hilfe für eine Desktop-Anwendung

Ausgangslage: Ein Hersteller einer komplexen Desktop-Software (CAD-Anwendung) lieferte bislang ein PDF-Handbuch aus, das Benutzer getrennt öffnen mussten. Viele Nutzer wünschten sich jedoch eine kontextsensitive Hilfe, also per F1-Taste direkt Hilfetexte zum aktuellen Dialog oder Fenster. Das bestehende Handbuch war monolithisch und nur in PDF vorhanden, zudem inhaltlich teilweise veraltet, da es mit den agilen Entwicklungs-Sprints nicht Schritt hielt. Die Technische Redaktion (2 Personen) stand vor der Herausforderung, knapp 150 Dialoge/Module der Software mit präzisen Hilfetexten abzudecken – und das in 5 Sprachen (Englisch als Ausgangssprache, plus Deutsch, Französisch, Spanisch, Chinesisch). Zudem sollte die Hilfe mit jeder neuen Minor-Version der Software aktualisiert werden können, ohne den gesamten Build-Prozess der Software zu verlangsamen.

Zielsetzung: Implementierung einer In-App-Hilfe, die leichtgewichtig ist (keine großen zusätzlichen Installationspakete), offline verfügbar (die Kunden arbeiten teils in isolierten Netzwerken) und genau auf das UI zugeschnitten. Jeder Dialog, jedes Fenster sollte einen eigenen Hilfetext erhalten, der aufrufbar ist, wenn der Nutzer Hilfe benötigt. Die Inhalte sollten zudem rollenspezifisch gefiltert werden können – z. B. eine einfache Erklärung für Endnutzer vs. tiefere technische Details für Administratoren, je nachdem wer eingeloggt ist. Das Redaktionsteam wollte auch eine Möglichkeit, Änderungen an der Software (neue Felder, geänderte Optionen) zeitnah in der Hilfe zu reflektieren, idealerweise synchron zum Entwickler-Sprint. Kurz: Weg von statischem PDF, hin zu dynamischer, kontextsensitiver Hilfe, ohne Qualität oder Übersetzungsstand zu kompromittieren.

Lösung: Das Team entschied sich, die Hilfe komplett topic-basiert mit DITA neu aufzubauen. Jeder identifizierte UI-Dialog wurde zu einem eigenen Thema (Topic). Als Topic-Typ wählte man meistens Task (sofern es sich um Dialoge handelt, bei denen der Nutzer etwas ausführen muss) oder Reference (für Nachschlage-Seiten, z. B. Erklärung aller Einstellungen eines Optionsfensters). Die Struktur der Topics wurde eng an das UI angelehnt: beispielsweise hieß ein Topic „Einstellungen > Benutzerverwaltung – Dialogbeschreibung“. Über eine eindeutige Kennung im Topic (im <topic id=““> Attribut) wurde die Verbindung zur Software hergestellt – die Entwickler versahen den „Hilfe“-Button jedes Dialogs mit dieser ID. Damit entstand eine Zuordnungstabelle: Dialog A ruft Topic A auf, Dialog B -> Topic B, etc. Für Profilierung sorgte man insofern, als dass bestimmte Abschnitte innerhalb eines Topics je nach Benutzerrolle sichtbar sind: Absätze mit tieferen technischen Hinweisen wurden mit audience=“admin“ markiert, sodass sie nur in der Admin-Dokumentation oder auf Anforderung erscheinen. Die DITA-Map der Hilfe folgte der Software-Menüstruktur, um auch ein browsbares Inhaltsverzeichnis zu bieten. Da viele UI-Elemente ähnlich waren, wurden gemeinsam genutzte Beschreibungen (etwa „Datei öffnen“-Dialog, der überall identisch funktioniert) als Snippet-Topics erstellt und per Conref in mehrere Hilfethemen eingebunden – das spart Zeit und vermeidet Widersprüche.

Toolchain/Automatisierung: Adobe FrameMaker kam hier ebenfalls zum Einsatz, insbesondere weil die Autoren damit im WYSIWYG-Modus die Formatierung und Layout-Anmutung der Hilfeseiten vorab sehen konnten. Die Einbindung der kontextsensitiven Logik erfolgte durch sogenannte Map-Dateien der Software: Die Entwickler hinterlegten in einer Konfigurationsdatei die Zuordnung von UI-Elementen zu den generierten HTML-Dateien. Gebaut wurden die Hilfeseiten mit dem DITA Open Toolkit im HTML5-Modus (lieferte ein Set von verlinkten HTML-Seiten, ein Suchindex und ein leichtgewichtiges CSS/JS-Framework für die Navigation). Wichtig: Man entschied sich bewusst gegen das alte WinHelp (.chm) Format und setzte auf rein HTML, um modern und plattformunabhängig zu sein. Die Publikationspipeline war in den Software-Build integriert – bei jedem neuen Release-Kandidaten wurde ein aktuelles Hilfepaket gebaut. Dabei wurde mittels Profilierungs-Ditaval z. B. eine User-Version und eine Admin-Version erzeugt (die Admin-Hilfe enthielt alle Details, die Endnutzer-Hilfe war gefiltert auf das Wesentliche). Die resultierenden HTML-Pakete waren sehr schlank (ein paar MB) und wurden als Teil des Installers ausgeliefert. Durch die Versionskontrolle der DITA-Quellen (Git) konnte parallel an Hilfetexten für kommende Versionen gearbeitet werden, ohne die veröffentlichte Hilfe zu beeinflussen. Das Übersetzungsmanagement lief über ein Lokalisierungstool, das die DITA-XML extrahierte; die übersetzten Segmente wurden wieder ins Projekt eingespeist und dann ebenfalls mit dem Toolkit gebaut.

Ergebnisse: Die neue In-App-Hilfe wurde von den Nutzern hervorragend aufgenommen. Nun öffnet sich bei Druck auf F1 oder Klick auf „Hilfe“ genau der relevante Hilfetext zum aktuellen Fenster. Insgesamt wurden ~150 Topics erstellt (für 150 Dialoge/Funktionen), was die früher ~600-seitige PDF in granulares, kontextspezifisches Wissen aufteilte. Durch Profilierung und clevere Strukturierung konnte die Zahl der tatsächlich ausgelieferten HTML-Seiten pro Variante reduziert werden – der Endnutzer sieht z. B. nur ~100 Seiten (da Admin-spezifische Inhalte ausgeblendet sind), während ein Administrator-Paket alle 150 enthält. Wiederverwendung: Rund 30% der Inhalte werden in mindestens zwei Topics genutzt, zum Beispiel Standard-Toolbar-Erklärungen oder wiederkehrende Bedienkonzepte. Das heißt, ein erheblicher Teil des Textes musste nur einmal übersetzt werden. Die Größe des Hilfepakets blieb mit ca. 5 MB sehr gering (unter 5% der Softwaregröße), was wichtig für Kunden mit wenig Bandbreite war. Aktualität: Durch die Integration in den Release-Prozess erreichten die Redakteure ihr Ziel, die Doku praktisch synchron mit der Software auszuliefern – kleinere Änderungen am UI (neue Feldbezeichnungen etc.) wurden oft innerhalb desselben Sprints in den Topics angepasst. In internen Tests konnten 95% der getesteten Anwendungsfälle abgedeckt werden, d.h. fast jeder Klick auf „Hilfe“ führte zu einem passenden Hilfetext (die restlichen 5% betrafen Randfälle, die im nächsten Update ergänzt wurden). Support-Aufwand sank: Das Kundensupport-Team berichtete, dass deutlich weniger Rückfragen zu grundsätzlicher Bedienung kamen („Wie mache ich X?“), da die Benutzer die Antworten sofort in der In-App-Hilfe fanden. Auch die Übersetzungsqualität profitierte – die Übersetzer konnten dank kleinerer Segmente und klarer Kontextangaben die Lokalisierung schneller und konsistenter erledigen.

Lessons Learned: Die Umsetzung der kontextsensitiven Hilfe lehrte das Team einige wichtige Punkte. Erstens: Frühe Planung der ID-Strategie ist essentiell. Es wurden alle Dialoge inventarisiert und mit eindeutigen IDs versehen, bevor die Dokumentation startete. Diese Zusammenarbeit mit den Entwicklern hat reibungslosere Integration ermöglicht. Zweitens: Keep it short and simple – Hilfetexte im Kontext sollten prägnant sein. Anfangs neigten die Autoren dazu, seitenlange Erklärungen ins Topic zu schreiben. Nutzertests zeigten aber, dass kurze, auf die direkte Frage bezogene Antworten besser ankamen. Daraufhin wurden manche Topics gesplittet oder gekürzt, was wiederum Wiederverwendung förderte (kleinere Bausteine lassen sich flexibler kombinieren). Drittens: Das Team stellte fest, dass Disziplin bei Profilierung wichtig ist. Man hatte zunächst sehr feingranular unterschieden (viele Bedingungen für verschiedene Nutzergruppen), was die Pflege erschwerte. Später wurden Profilierungen vereinfacht (Hilfe grundsätzlich in zwei Varianten: Endnutzer vs. Admin), was die Sache handhabbar machte. Zuletzt die Erkenntnis, dass Feedback-Schleifen mit Nutzern enorm wertvoll sind: Die In-App-Hilfe wurde nach Release durch Nutzerfeedback weiter verbessert – z. B. wurden zusätzliche Querverlinkungen eingebaut, wo Nutzer stockten. DITA ermöglichte diese Änderungen sehr effizient einzupflegen. Insgesamt zeigt das Beispiel, dass ein Umstieg von statischem Handbuch zu lebendiger In-App-Hilfe mit DITA gelingen kann, wenn man Technik (Mapping, Build) und Inhalt (strukturierte kurze Topics) abgestimmt angeht.

4.3 Release-Notes & Änderungsprotokolle in einem CI-Prozess

Ausgangslage: In einem Unternehmen mit kontinuierlicher Softwareentwicklung (DevOps-Modell) wurden Release-Notes bislang manuell in Word zusammengestellt. Das bedeutete: kurz vor jedem Release-Datum ging ein Technischer Redakteur die Liste der Jira-Tickets und Git-Commits durch, kopierte relevante Beschreibungen in ein Dokument und formatierte diese als Release Note. Für unterschiedliche Produkteditionen (Standard, Enterprise) wurden separate Dokumente erstellt – oft mit redundanten Inhalten. Ebenso gab es für jede der 3 unterstützten Sprachen eigenständige Dateien, die via Copy-Paste übersetzt wurden. Dieses Vorgehen war fehleranfällig (ein vergessenes Feature hier, ein falscher Screenshot da) und zeitaufwendig: ~2–3 Tage Arbeitszeit flossen in jede Release-Dokumentation. Zudem war es schwierig, das Änderungsprotokoll historisch konsistent zu halten; es fehlte ein zentral gepflegtes Archiv.

Zielsetzung: Die Dokumentation der Änderungen sollte möglichst automatisiert und aktuell erfolgen, idealerweise parallel zum Entwicklungszyklus. Konkrete Ziele: Tägliche Aktualisierung eines Änderungslogs (damit Teams intern jederzeit den Stand sehen können), Profilierung nach Edition (Features, die nur Enterprise-Kunden betreffen, sollen in den Standard-Release-Notes nicht auftauchen und umgekehrt) und Erzeugung mehrsprachiger Release-Notes mit minimalem manuellem Aufwand. Außerdem sollten die Release-Notes nicht nur am Ende als PDF vorliegen, sondern auch im Web (z. B. als Teil der Online-Dokumentation) veröffentlicht werden. Kurz: ein CI-gestützter Workflow, der Release-Notes zu einem kontinuierlichen Prozess macht statt zu einer einmaligen Hauruck-Aktion pro Release.

Lösung: DITA wurde als Grundlage gewählt, um die kleinteiligen Änderungseinträge strukturiert zu erfassen. Man führte einen neuen Topic-Typ ein, faktisch basierend auf Reference: sogenannte „Change-Topics“ – jedes steht für ein Ticket oder eine Feature-Änderung. Ein Change-Topic enthält z. B. als Titel die Kurzbeschreibung („Neue Filterfunktion im Modul X“), im Body Details, ggf. Screenshots oder Code-Auszüge, und Metadaten wie Ticket-ID, Kategorie (Feature/Bugfix) und betroffene Edition. Die Redakteure richteten zunächst eine DITA-Map „Release-Notes aktuell“ ein, in der alle neuen Change-Topics landeten. Diese Map war nach Kategorien strukturiert (erst neue Features, dann Verbesserungen, dann Bugfixes). Wiederverwendung kam z.B. bei standardisierten Einleitungstexten oder wiederkehrenden Hinweisen zum Einsatz (etwa ein allgemeiner Abschnitt „Dieses Release erfordert ein Datenbank-Update“, der per Conref in mehreren Release-Notes auftaucht). Für Editionen wurde Profilierung genutzt: Jedes Change-Topic hatte ein Attribut edition=“Enterprise“ oder „Standard“ oder beide. Die Map konnte somit gefiltert publiziert werden, um z. B. eine „Standard Release Note“ zu erzeugen, die Enterprise-exklusive Punkte ausblendet. Um den Prozess zu automatisieren, entwickelte das Team Hooks im Ticketsystem: Wenn ein Jira-Ticket den Status „Done“ erreichte und als „Dokumentationsrelevant“ markiert war, wurde dessen Inhalt (Beschreibung, Changelog-Eintrag) in ein DITA-Topic-Template überführt. Ein Redakteur prüfte dieses generierte Topic, passte Stil und Überschrift ggf. an und ergänzte fehlende Kontextinfos. Dieser semi-automatische Weg sparte viel Tipparbeit, ließ aber menschliche Qualitätskontrolle zu. Die Publikation erfolgte mit DITA-OT: Einmal täglich wurde ein Nightly Build der Release-Notes-Map durchgeführt. Das DITA-OT generierte sowohl HTML5 (für eine Web-Doku-Seite „Änderungen in der Nightly Build“) als auch PDF (für interne Verteilung an Stakeholder, die das offline lesen wollten). Am eigentlichen Release-Tag wurde dann ein PDF freeze gemacht und dieses an Kunden versendet, während im Web die HTML-Fassung aktualisiert wurde. Für Sprachen: Die Change-Topics wurden frühzeitig (alle 1–2 Tage) den Übersetzern in kleinen Portionen übermittelt, statt am Schluss ein Riesenpaket. So waren die meisten Texte zum Releasezeitpunkt bereits übersetzt vorhanden und brauchten nur noch final konsolidiert zu werden.

Toolchain/Automatisierung: Kernelement war die Integration in die CI/CD-Pipeline. Auf dem Jenkins-Server lief ein Job, der alle 24 Stunden das Repository mit den DITA-Change-Topics checkte und DITA-OT ausführen ließ. Parameter für Filter (Edition) wurden dabei so gesetzt, dass gleich zwei Versionen erzeugt wurden – eine Standard und eine Enterprise. Diese Outputs (HTML) lagen auf einem internen Webserver für das Team. Die Autoren benutzten tagsüber FrameMaker, um ggf. mehrere kleine Change-Topics zu einem größeren Eintrag zu konsolidieren oder Screenshots einzufügen. FrameMaker’s DITA-Unterstützung half auch beim Vergleich von Versionen: man konnte z. B. einfach sehen, welche Topics seit gestern neu hinzugekommen sind (Versionsvergleich), um den Überblick zu behalten. Übersetzungen wurden mittels eines Scripts aus dem DITA-Format in CSV-Tabellen extrahiert, den Übersetzern gegeben und wieder zurückgeführt (da die Texte recht klein waren, verzichtete man hier auf XLIFF-Prozess – es ging schneller per Tabellenexport/-import). DITA-OT erzeugte für PDF-Ausgabe ein angepasstes Layout mit dem Firmenlogo und einem Release-Note-typischen Titelblatt; hierzu wurde ein PDF2-Plugin konfiguriert. Insgesamt war die Toolchain so eingestellt, dass zumindest 90% der Release-Note-Erstellung ohne menschliches Zutun ablief – Menschen griffen nur ein zum Kuratieren der Inhalte und finalen Abnahme.

Ergebnisse: Die Einführung dieses DITA-basierten Workflows wandelte die Release-Notes von einem Problemkind zu einem Vorzeigeprozess. Aktualität: Zu jedem beliebigen Zeitpunkt während der Entwicklung konnte nun ein fast aktueller Stand der kommenden Release-Notes eingesehen werden. Überraschungen kurz vor knapp wurden eliminiert. Aufwandsreduktion: Die manuelle Arbeitszeit für die Erstellung sank um geschätzte 80–90%. Statt Tage an einem Dokument zu formatieren, beschränkte sich die Arbeit der Redakteure auf die inhaltliche Kontrolle und gelegentliche Nacharbeiten pro Eintrag. Genauigkeit: Fehlende Einträge wurden seltener – durch die Systematik (jedes Ticket löst idealerweise ein Topic aus) gingen viel weniger Änderungen unter. Die Release-Notes deckten nach interner Analyse ~99% aller tatsächlich umgesetzten Storys und Fixes ab (vorher oft nur ~85%, weil manches unter den Tisch fiel). Kundenzufriedenheit: Die Kunden lobten die Klarheit der neuen Release-Notes. Durch die konsistente Struktur (immer erst Features, dann Bugfixes, mit identischen Formulierungen wie im Issue Tracker) fanden sie schneller relevante Infos. Enterprise-Kunden bekamen ein eigenes Dokument, was Verwirrung vermied – vorher standen dort mitunter Funktionen, die nur die Enterprise-Version hatte, was Standard-Kunden irritierte. Übersetzung: Hier zahlte sich die stückweise Lokalisierung aus. Die Übersetzer konnten ~70% der Sätze aus vorigen Release-Notes wiederverwenden (Wiederholungen wie „behobener Fehler im Modul X“ waren dank DITA-Wiederverwendung identisch formuliert) und neuen Content schrittweise übersetzen. Somit lagen zum Release-Datum alle 3 Sprachen fertig vor. Die Übersetzungskosten pro Release sanken laut Controlling um ~25%, da weniger Ad-hoc-Übersetzungen im Eiltempo nötig waren und Translation-Memory besser genutzt wurde. Interne Qualitätssicherung: Durch den täglichen Build wurden potenzielle Probleme früh sichtbar (z. B. fehlende Screenshots, formale Fehler in Topics). Diese konnten vor dem eigentlichen Release leicht behoben werden. Auch das Audit-Trail wurde besser: Für jede Version existiert nun ein archiviertes DITA-Map und Ausgaben, sodass man Monate später noch nachvollziehen kann, was genau kommuniziert wurde.

Lessons Learned: Ein wichtiges Lernfeld war die Kultur des kontinuierlichen Dokumentierens. Zu Beginn mussten Entwickler daran erinnert werden, Tickets sauber zu pflegen, damit aus den Beschreibungen auch verständliche Release-Notes entstehen. Hier wurde im Team vereinbart, dass Entwickler in Jira ein spezielles Feld „Für Kunden sichtbare Änderung“ ausfüllen – quasi die Laienfassung des technischen Fixes. Diese Texte wurden dann 1:1 ins DITA-Topic übernommen, was Aufwand sparte. Zudem lernte das Team, dass Konsistenz in der Sprache entscheidend ist. Indem man feste Phrasen definierte („Behoben: …“, „Neu: …“), wirken die Release-Notes wie aus einem Guss, selbst wenn viele Autoren daran schreiben – DITA ermöglichte diese Konsistenz durch Snippet-Wiederverwendung. Bei der Profilierung stellte sich heraus, dass weniger mehr ist: Man behielt es bei dem einen Kriterium Edition (Standard/Enterprise) und verzichtete auf weitere Untervarianten, um den Pflegeaufwand gering zu halten. Technisch gesehen war es lehrreich, das DITA-OT in CI zu integrieren – die Admins stellten sicher, dass die Build-Umgebung genau zu FrameMaker passte (die gleiche DITA-OT-Version), damit es keine Unterschiede zwischen lokalem Preview und CI-Output gab. Abschließend war die Akzeptanz bei den Lesern ein Punkt: Man sammelte Feedback von Support und Kunden zu den neuen Release-Notes und passte Kleinigkeiten an (z. B. in HTML eine bessere Suchfunktion). Das Fazit war einstimmig positiv – der automatisierte Prozess lieferte verlässlichere, vollständigere und professioneller aussehende Release-Notes bei deutlich geringerem Aufwand.

4.4 Mehrsprachige Administrator- und Installationshandbücher

Ausgangslage: Ein mittelständisches IT-Unternehmen bietet eine komplexe On-Premises-Software an, die beim Kunden installiert und konfiguriert werden muss. Dazu gab es zwei umfangreiche Handbücher: ein Installationshandbuch (für die technische Installation auf Windows, Linux, etc.) und ein Administrator-Handbuch (für die spätere Konfiguration, Benutzerverwaltung, Wartung). Diese Dokumente existierten in mehreren Sprachen (Englisch, Deutsch, Französisch) und wurden traditionell in Word gepflegt. Problem: Große Überschneidungen zwischen den Handbüchern führten zu doppelter Pflege. Beispiel: Die Beschreibung, wie die Datenbankverbindung einzurichten ist, stand im Installationsguide und im Admin-Guide ähnlich drin – aber nie 100% gleich, weil verschiedene Autoren daran arbeiteten. Plattformunterschiede (Win vs. Linux) wurden mit roten Textstellen markiert oder in Klammern gesetzt, was unübersichtlich war. Neue Softwareversionen (jährliche Releases + Zwischensprachpakete) zu dokumentieren wurde immer schwerfälliger, weil man bei jeder Änderung drei Dokumente pro Sprache anfassen musste. Das Team (eine leitende Redakteurin plus externe Übersetzer) suchte nach einer Lösung, um diesen Aufwand in den Griff zu bekommen.

Zielsetzung: Zentral war die Wiederverwendung und Konsolidierung der Inhalte. Konkret sollte eine einheitliche Dokumentationsbasis geschaffen werden, aus der verschiedene Ausgaben generiert werden: Installationshandbuch und Admin-Handbuch, jeweils für Windows und Linux (ggf. als kombinierte Ausgabe mit klar getrennten Abschnitten), und das Ganze in allen erforderlichen Sprachen. Dadurch erhoffte man sich konsistentere Doku (jede Information nur einmal gepflegt), weniger Übersetzungsvolumen und die Möglichkeit, schneller auf Änderungen zu reagieren. Auch sollte die Qualität steigen – bisher schlichen sich oft Fehler ein, wenn z. B. ein Linux-Befehl im deutschen Handbuch aktualisiert, aber im englischen vergessen wurde. Mit einer Single-Source-Lösung (DITA) wollte man das vermeiden. Zudem stand die Idee im Raum, zukünftig auch Release-Notes und Benutzerhandbücher (für Endanwender) in das gleiche System zu integrieren, daher sollte die Lösung skalieren können.

Lösung: In einem Migrationsprojekt überführte man die existierenden Word-Inhalte in DITA-Topics. Dabei wurden harte Schnitte gemacht: Jedes Kapitel oder Unterkapitel wurde zu einem eigenen Topic (so entstanden rund 250 Topics aus beiden Handbüchern). Diese Topics wurden thematisch gruppiert – z. B. alle Installationsschritte in einen Ordner, alle Konfigurationsanleitungen in einen anderen. Wichtig war, plattform- und produkt-spezifische Inhalte sauber zu trennen. Man führte daher das Attribut platform ein, um Anweisungen zu markieren, die nur für Windows oder nur für Linux gelten. Beispiel: Ein Topic „Dienst starten“ hat zwei Abschnitte, einen mit platform=“windows“ (betrifft Windows-Dienststeuerung) und einen mit platform=“linux“ (betrifft systemd auf Linux). Zur besseren Übersicht legte man diese Abschnitte auch als separate Unterthemen an und band sie per Conref abhängig vom Output ein. Produktvarianten hatte die Software zwar keine diametral unterschiedlichen, aber zwischen Standard und Enterprise Edition gab es Unterschiede bei einigen Features – auch hier kam Profilierung zum Einsatz (attribute product=“enterprise“ an bestimmten Sätzen). Anschließend erstellte das Team zwei DITA-Maps: eine für Installation, eine für Administration. Beide Maps referenzierten großzügig gemeinsame Topics. Zum Beispiel wurden die Kapitel zu Benutzerverwaltung, Backup & Recovery im Admin-Guide und Installations-Guide gleichermaßen benötigt – in DITA liegen sie nun einmal vor und tauchen in beiden Publikationen per Reference auf. Keys nutzte man unter anderem für Produktnamen und Versionen: Der Firmenname und Produktname waren an einigen Stellen unterschiedlich zu schreiben (Branding-Regeln in verschiedenen Sprachen), was man elegant über Key-Einträge löste und nicht mehr im Fließtext hart codieren musste. Die Übersetzung wurde von Anfang an mitgedacht: Die englischen Topics dienten als Master; man implementierte ein Translation Memory Workflow, bei dem geänderte Topics in ein TMS (Translation Management System) eingespeist wurden. Durch DITA-IDs blieb eindeutig, welche Segmente schon übersetzt sind und welche neu sind – das TMS konnte somit nur die Änderungen übersetzen lassen, anstatt jedes Mal das ganze Handbuch.

Toolchain/Automatisierung: Bei diesem Projekt kam ebenfalls Adobe FrameMaker zum Einsatz, vor allem weil die Redakteurin es gewohnt war und damit schnell in den neuen Strukturen arbeiten konnte. FrameMaker wurde so konfiguriert, dass die Profilierungsattribute (platform, product, audience etc.) farblich hervorgehoben im Editor erscheinen – so behielt man im WYSIWYG-Modus den Überblick, welche Texte wofür gelten. Für die Publikation setzte man auf einen bewährten Ansatz: Das DITA-OT generierte PDF-Handbücher (da viele Kunden ein PDF erwarteten) und parallel HTML5-Ausgaben für die Web-Dokumentation. Das PDF-Layout wurde in FrameMaker entworfen und via FrameMaker Publish auf DITA-OT abgestimmt – man erreichte so qualitativ hochwertige PDF-Dateien mit korrektem Inhaltsverzeichnis, Index und CI-gerechtem Erscheinungsbild, ohne Nachbearbeitung. Da unterschiedliche Ausgaben benötigt wurden (insgesamt 2 Handbuchtypen × 2 Sprachen = 4 PDF, analog 4 HTML-Bereiche), automatisierte man die Erstellung mit einem Batch-Skript. Dieses lief bei jedem neuen Release und erzeugte in einem Rutsch alle Varianten, indem es die entsprechenden Ditaval-Filter setzte (z. B. windows vs linux Filterlauf) und die richtige Sprachmap auswählte. Die Versionierung wurde mittels Git verwaltet; vor einem größeren Release wurde ein Branch erstellt, sodass nachträgliche Korrekturen für Patch-Versionen isoliert eingespielt werden konnten. Für die Übersetzer generierte man aus dem DITA-Repo XLIFF-Dateien – ein Automatik-Skript extrahierte alle neu geänderten oder neuen Topics seit dem letzten Release. Diese XLIFF wurden vom Sprachendienst übersetzt und dann in die XML zurückgeführt. So sparte man den bisherigen manuellen Abgleich von drei Word-Dokumenten je Sprache.

Ergebnisse: Die Konsolidierung der Handbücher in DITA zeigte deutliche Verbesserungen. Wiederverwendungsquote: Etwa 70% des Inhalts des Admin-Handbuchs wird auch im Installationshandbuch genutzt oder ist zumindest daraus abgeleitet. Die Gesamtwortanzahl aller Handbücher konnte durch DITA um ~40% reduziert werden (gegenüber der Summe der Worte in den alten separaten Dokumenten) – ein direktes Maß für eliminierten redundanten Text. Pflegeaufwand: Wenn jetzt eine Änderung ansteht (z. B. neuer Parameter in der Konfigurationsdatei), wird diese an einer Stelle im passenden Topic durchgeführt. Früher musste man 3 PDFs und 2 Sprachen durchsuchen, um überall die Referenzen zu erwischen; jetzt fließt die Änderung automatisch in alle betroffenen Publikationen. Die Redakteurin gibt an, dass pro Release nun ca. 30% weniger Zeit für die Doku-Aktualisierung gebraucht wird, weil viele Tätigkeiten (Suche nach gleichen Textstellen, mehrfaches Anpassen) entfallen. Übersetzungseffizienz: Für die Übersetzer bedeutete DITA einen großen Sprung: In dem ersten Release nach Umstellung sank der neu zu übersetzende Anteil der Texte um ~45%, da durch die Zusammenlegung viele Texte bereits in der vorherigen Version übersetzt worden waren und nun in beiden Handbüchern wiederverwendet wurden. Zudem verbesserte sich die Konsistenz der Terminologie zwischen Installations- und Admin-Handbuch, weil beide nun denselben englischen Ursprung haben – Unterschiede (z. B. ein Begriff mal als „Datenbank“ mal als „Datenbankinstanz“ übersetzt) wurden eliminiert. Qualität & Fehlerdichte: Nach dem ersten DITA-basierten Release wurde ein internes Audit der Handbücher durchgeführt. Die Anzahl an gefundenen Fehlern/Inkonsistenzen ging signifikant zurück (um ca. 50% weniger Beanstandungen), insbesondere gab es kaum noch Widersprüche zwischen dem Installations- und Admin-Teil. Die Reviewer lobten, dass das Layout und die Struktur jetzt über alle Dokumente hinweg einheitlicher und leichter navigierbar ist (z. B. gleiche Kapitelreihenfolge in allen Sprachen, dank gemeinsamer Map-Struktur). Time-to-Publish: Durch den automatisierten Build und parallele Übersetzung verkürzte sich die Zeit vom Code-Freeze bis zur fertigen Doku-Auslieferung. Früher erschien die deutsche Doku oft erst 4–6 Wochen nach dem englischen Release; jetzt liegen alle Sprachversionen innerhalb 1–2 Wochen vor. Dies ist besonders aus Compliance-Sicht relevant, da in einigen Märkten (Frankreich) vorgeschrieben ist, dass die Lokalisierung zeitnah verfügbar sein muss.

Lessons Learned: Ein Schlüssellearning war die Notwendigkeit eines klaren Inhaltsmodells vorab. In der Migrationsphase hat man viel Zeit investiert, um die richtige Aufteilung der Topics zu finden – dieser Aufwand zahlte sich aus. Die Redakteurin merkte an, dass sie anfänglich geneigt war, „zu große“ Topics zu belassen (z. B. ein gesamtes Kapitel als ein Topic). Später stellte sich heraus, dass kleinere, thematisch fokussierte Topics besser wiederverwendet und übersetzt werden konnten. Daher wurde im Verlauf noch weiter modularisiert (Lesson: lieber feiner granulare Topics und bei Bedarf mit Map strukturieren, als wenige Riesen-Themen). Ein weiterer Punkt: Profilierungsmanagement. Anfangs definierte man sehr viele Bedingungsattribute (für jede Plattform, Edition, Sprache separat). Das Team stellte fest, dass das teilweise überflüssig war – insbesondere wurden Sprachvarianten besser über separate Übersetzungsdateien als über Profilierung gelöst. Man konsolidierte die Profilierung schließlich auf drei Kernaspekte (platform, edition, audience) und fuhr damit besser. Auch musste man intern Überzeugungsarbeit leisten: Einige Kollegen trauerten dem Word-Format nach, da sie dort ad-hoc Änderungen machen konnten. Mit Schulung und dem klaren Hinweis auf die Vorteile (Zeitersparnis, Qualität) gelang aber der Change – heute möchten sie nicht zurück. Für die Übersetzer war das neue Format ebenfalls eine Umstellung. Lesson: Übersetzer früh einbeziehen. Man organisierte einen Workshop mit dem Übersetzungsbüro, um DITA zu erklären und die XLIFF-Schnittstelle zu testen. Dadurch konnten potenzielle Probleme (z. B. Umgang mit Variablen/Keys in Texten) vorab geklärt werden. Abschließend erkannte das Management den Mehrwert auch zahlenmäßig – geringere Kosten, schnellere Bereitstellung. Das half, die Entscheidung zu untermauern, zukünftig weitere Dokumentationsteile auf DITA umzustellen (z. B. plant man nun auch die Endbenutzer-Dokumentation ins DITA-Framework zu integrieren, um maximalen Reuse zwischen Admin- und User-Doku zu erreichen).

4.5 SaaS-Produktdoku mit Rollen- und Kundenvarianten

Ausgangslage: Ein Softwareanbieter betreibt ein Software-as-a-Service (SaaS)-Produkt, das für verschiedene Unternehmenskunden leicht angepasst wird (Stichwort Mandantenfähigkeit und White-Labeling). Das heißt, der Kern der Anwendung ist für alle gleich, aber einzelne Großkunden erhalten eigene Zusatzmodule oder Branding (Logo, Begriffe). Zudem gibt es innerhalb der Anwendung verschiedene Benutzerrollen (z. B. Endbenutzer, Team-Manager, Administrator), die jeweils unterschiedliche Funktionen sehen. Bisher wurde die Dokumentation so gehandhabt, dass pro Kunde ein separates Online-Handbuch gepflegt wurde, in dem kundenindividuelle Screenshots und Begriffe eingearbeitet waren – was dazu führte, dass das Doku-Team (4 Personen) faktisch 5 nahezu identische Handbücher parallel pflegte. Änderungen am allgemeinen Teil mussten in alle Kopien übertragen werden. Fehlerquote und Aufwand waren entsprechend hoch. Auch war es schwierig, eine einheitliche Qualität sicherzustellen, da sich die Dokumente teils auseinanderentwickelten. Ein weiteres Problem: Die Release-Frequenz war hoch (alle 2 Wochen ein Update), so dass das Team kaum nachkam, die Doku für jeden Kunden aktuell zu halten.

Zielsetzung: Es sollte eine einzelne, zentrale Dokumentationsbasis geschaffen werden, aus der sich die verschiedenen Varianten für Kunden und Rollen ableiten lassen. Das bedeutet: Gemeinsam genutzter Inhalt soll nur einmal vorhanden sein, kundenspezifische Unterschiede aber trotzdem berücksichtigt werden. Die Dokumentation sollte weiterhin als Web-Portal und PDF verfügbar sein – möglichst automatisch generiert für jeden Kunden (so dass z. B. Kunde A sein PDF-Handbuch mit seinem Logo und Features bekommt, Kunde B entsprechend mit seinen Anpassungen). Auch die Benutzerrollen wollte man dokumentatorisch trennen: Ein Endanwender soll nicht mit Admin-Informationen verwirrt werden und vice versa. Gleichzeitig war klar, dass die Autoren nicht exponentiell mehr Arbeit haben dürfen; sprich, Reuse und Automatisierung mussten maximal ausgeschöpft werden, um dem 2-Wochen-Releasezyklus standzuhalten.

Lösung: Das Team entschied sich, DITA mit konsequenter Profilierungsstrategie einzusetzen. Zunächst wurde das gesamte Doku-Wissen in ein Satz von DITA-Topics überführt (aus den zuvor getrennten Confluence-Wikis der Kunden). Dabei definierte man für jeden Inhalt, ob er global (für alle Kunden) oder kundenspezifisch ist. Globale Inhalte wurden als normale Topics erstellt. Kundenspezifische Besonderheiten – z. B. ein anderer Modulname, ein zusätzliches Kapitel nur für Kunde X – wurden als konditionale Elemente angelegt: Jedes Topic oder Element, das nur Kunde X sehen soll, trägt ein Profil-Attribut customer=“X“. Ähnlich wurden Benutzerrollen abgebildet: Informationen, die nur für Administratoren relevant sind, erhielten z. B. audience=“Admin“. Diese Attribute erlaubten es, aus dem selben Content-Pool unterschiedliche Sichtweisen zu generieren. Um Branding-Unterschiede (Logos, Produktnamen) elegant zu handhaben, nutzte man intensiv das Key/Schlüssel-Konzept: In einer DITA Key-Datei pro Kunde wurden zentrale Begriffe definiert, z. B. ProductName = „AcmeCloud“ für Kunde Acme, während dieselbe Key-ID für Kunde Beta = „BetaCloud“ zugewiesen bekam. Im eigentlichen Topic-Text stand dann nur <keyref name=“ProductName“/>, und beim Publizieren zog jeder Output die passende Zuordnung. Auch Screenshots, die leichte Unterschiede zeigten (z. B. ein anderes Logo im UI), wurden über Keys gelöst: Man legte je Kunde einen Verweis auf das entsprechende Bild an, und im Topic wurde mit <keyref> ein allgemeiner „LoginScreen.png“ referenziert, der je nach Kundenbuild auf die richtige Datei zeigte. Die DITA-Maps wurden so organisiert, dass es eine Hauptmap „SaaS-Dokumentation Gesamtsystem“ gab, die alle Topics enthielt. Diese wurde jedoch gefiltert publiziert. Für jeden Kunden erstellte man eine kleine Shell-Map, die auf die Master-Map referenzierte, aber mit einem Profilfilter (customer=A, audience je nach Rollendoku) versehen war. Daraus ergab sich pro Kunde und Rollentyp eine eigene Sicht. Beispielsweise generierte man: Admin-Doku Kunde Acme (alle Admin-Topics, customer=A), User-Doku Kunde Acme (nur Endnutzer-Topics, customer=A), Admin-Doku Kunde Beta, etc. Theoretisch entstanden so zwar viele Varianten, aber dank Automatisierung musste das niemand manuell zusammenklicken.

Toolchain/Automatisierung: Im täglichen Arbeiten nutzte das Team einen DITA-fähigen Editor (teils Oxygen XML, teils FrameMaker – je nachdem, womit der jeweilige Redakteur vertraut war; die Dateien lagen in Git, wodurch mehrere Tools parallel genutzt werden konnten). Für die Massenpublikation wurde ein Skript entwickelt, das iterativ für jeden definierten Kunden die Ausgabe erzeugt. Die Redakteure führten dieses Skript z. B. am Ende eines Sprints aus, um alle aktuellen Dokumente zu generieren. Das Skript setzte die benötigten Parameter für DITA-OT: Es lud die Master-Map mit dem entsprechenden filter (Ditaval, welches customer=X enthält) und generierte sowohl HTML5 als auch PDF. Adobe FrameMaker kam ergänzend zum Einsatz, um die PDF-Templates für jeden Kunden einzurichten – insbesondere Logos und Farbthemen. Allerdings machte man das geschickt: Statt für jeden Kunden eine eigene FrameMaker-Vorlage zu erstellen, wurden Logos ebenfalls über Keys eingefügt, und das PDF-Stylesheet zog das Key-entsprechende Logo. So blieb die Anzahl der Templates minimal. Continuous Integration: Mittelfristig band man diese Generation in die CI-Pipeline ein. D.h., bei jedem Software-Release-Kandidaten löste der Build-Server automatisch auch den Doku-Build aus und legte die neuen Doks auf einem internen Portal ab. Damit konnten Vertrieb und Kundenbetreuer vorab sehen, ob die Dokumentation vollständig und korrekt angepasst ist. Eine Herausforderung waren die vielen Profilkombinationen – man testete das System intensiv, um sicherzustellen, dass keine ungewollten Lecks entstehen (z. B. ein nur für Admin bestimmter Satz versehentlich in der User-Doku). Hier halfen automatische Prüfscripte, die nach bestimmten Markern suchten.

Ergebnisse: Diese DITA-Implementierung führte zu einer dramatischen Reduktion des Pflegeaufwands. Aus vormals 5 separaten Kundenhandbüchern mit weit über 1000 Seiten Gesamtumfang wurde eine Single-Source-Sammlung von ca. 300 Topics. Der Clou: Jedes dieser Topics fließt je nach Relevanz in 1, 2 oder alle Kundendokumente ein. Die Wiederverwendungsrate des Textes liegt bei ~85% über alle Kunden – das heißt, ein Großteil der Inhalte ist generisch und wird für jeden Kunden gleich mit ausgeliefert. Nur etwa 15% sind spezifische Abweichungen. Dadurch konnten zwei der vier Redakteure, die früher fast voll mit Copy-Paste-Beschäftigung für Kundendokus waren, auf inhaltlich wertvollere Aufgaben wechseln (z. B. Ausbau einer Knowledge Base). Konsistenz: Die Kunden erhalten nun Dokumentationen, die zu ~90% gleich sind – was gewollt ist, denn die Software kann ja bewusst nur begrenzt unterschiedlich sein. Unterschiede, etwa andere Modulnamen, sind klar und konsistent eingepflegt. Kundenrückmeldungen waren positiv: Einige hatten vorher bemängelt, dass ihre Dokumentation im Vergleich zu anderen weniger ausführlich war (weil da mal was ausgelassen wurde); jetzt haben alle dieselbe Basisqualität. Skalierung: Als ein neuer Großkunde (Kunde F) hinzukam, konnte innerhalb weniger Tage für diesen auf Basis der Single-Source-Daten eine vollständige Dokuvariante erzeugt werden – früher hätte man ein eigenes Handbuch neu erstellen oder ein existierendes komplett kopieren und anpassen müssen (Wochenaufwand). Jetzt reichte es, wenige Keys für den Kundennamen zu setzen und spezifische Module zu profilieren, und das meiste ergab sich von selbst. Release-Zyklen: Trotz 2-wöchigem Sprint schafft es das Team nun, zeitgleich mit dem Software-Update auch alle Kunden-Dokumentationen bereitzustellen. Die automatisierte Pipeline generiert über Nacht alle Varianten, das wäre manuell unmöglich gewesen. Übersetzung: In diesem Beispiel war die Primärdokumentation auf Englisch, doch eine Lokalisierung ins Spanische und Deutsche wurde ebenfalls gefordert. Der modulare Ansatz kam auch hier zugute – viele wiederverwendete Topics bedeuteten weniger zu übersetzende Worte. Das Lokalisierungsteam gab an, dass sich der Übersetzungsaufwand um ~30% reduziert hat, da einmal übersetzte Sätze für alle Kundenvarianten galten. Zudem brauchte man nicht mehr für jeden Kunden separate Übersetzungsprojekte aufsetzen; es läuft zentral über die Master-Topics.

Lessons Learned: Dieses anspruchsvolle Variantenmanagement lieferte wertvolle Erkenntnisse. Eine zentrale Lektion: Komplexitätsbeherrschung. Zu Beginn versuchte man, alles per Profil zu lösen – es entstand ein Wildwuchs an Attributen (customer, industry, role, edition, etc.). Schnell wurde klar, dass das unübersichtlich wird. Daher besann man sich auf Kernvariablen: customer und audience reichten hier, da Editionen keine großen Unterschiede hatten. Und statt für jede kleine Abweichung eine Bedingung zu setzen, entschied man in manchen Fällen, lieber ein komplett separates Topic zu erstellen (z. B. wenn ein Modul nur Kunde X hat, bekam Kunde X ein zusätzliches Topic, statt überall „nur für X“ zu taggen). Das war leichter zu warten. Ein weiterer Punkt: Key-Verwaltung. Mit über 5 Kunden und ~50 Keys (für Produktnamen, Modulnamen, Logos, Firmennamen etc.) wuchs die Key-Definition auf. Man stellte fest, dass eine saubere Benennung und Dokumentation dieser Schlüssel essentiell ist. Ein Fehler in der Key-Zuordnung hätte z. B. falsche Firmennamen in ein Kundenhandbuch bringen können – daher hat man ein Peer-Review eingeführt speziell für Änderungen an den Key-Dateien. Zudem zeigte sich, dass Kommunikation mit Stakeholdern wichtig ist: Vertrieb und Kunden mussten zunächst verstehen, warum die Doku jetzt etwas generischer aussieht („Unser Firmenname steht überall als Parameter drin, nicht mehr im Fließtext“). Nachdem man es erläuterte und die Vorteile klarmachte (schnellere Updates, weniger Fehler), waren aber alle überzeugt. Schließlich noch ein praktischer Tipp: Das Team lernte, die Builds regelmäßig zu testen. Gerade bei vielen Varianten kann es passieren, dass eine seltene Kombination erst spät auffällt. Durch wöchentliche Test-Builds aller Kunden-Dokus entdeckte man etwa inkorrekte Bild-Verweise früh genug. Insgesamt bewies dieses Projekt, dass mit DITA selbst eine hoch konfigurierte, mehrmandantenfähige Dokumentation machbar ist – aber es erfordert diszipliniertes Vorgehen, clevere Nutzung der DITA-Features und ständige Überprüfung der Ergebnisse.

5. Adobe FrameMaker als Werkzeug für DITA-Inhalte

Bei der Umsetzung von DITA-Szenarien spielt oft die Wahl des richtigen Tools eine große Rolle. Adobe FrameMaker ist ein etabliertes Authoring-Werkzeug, das seit vielen Jahren in der Technischen Dokumentation verwendet wird und nativ DITA unterstützt. Im Folgenden wird FrameMakers Rolle im DITA-Prozess, seine Kernfunktionen, Stärken sowie einige Grenzen und Best Practices beleuchtet – speziell im Kontext von Softwaredokumentation.

Rolle im DITA-Prozess: FrameMaker fungiert als strukturierter Editor für DITA-Inhalte. Anstatt XML-Code von Hand schreiben zu müssen, arbeiten Autoren in einer WYSIWYG-Umgebung, die dennoch die strikte DITA-Struktur im Hintergrund gewährleistet. FrameMaker lädt die jeweiligen DITA-DTD/Schema (z. B. für Task, Concept, Reference) und sorgt dafür, dass der Autor nur erlaubte Elemente einfügen kann. Damit wird das Schreiben deutlich komfortabler, ohne die Konsistenz zu gefährden. FrameMaker wird oft als zentrales Redaktionswerkzeug eingesetzt: Autoren erstellen und bearbeiten Topics und Maps damit, prüfen die Darstellung, und können direkt aus FrameMaker heraus publizieren. Das Tool lässt sich außerdem in Redaktionsleitfäden einbinden: Man kann z. B. eigene Vorlagen/Templates definieren, die sicherstellen, dass jedes neue Topic bereits mit den richtigen Tags und Formatvorlagen startet (z. B. ein Task-Topic hat automatisch <title>, <taskbody>, <steps> vorbereitet). In Teamumgebungen bietet FrameMaker Möglichkeiten zur Kollaboration, etwa durch Anbindung an CMS (Content Management Systeme) oder Nutzung von Shared Repositories.

Kernfunktionen: Adobe FrameMaker deckt eine Vielzahl von Funktionen für DITA-Authoring ab, darunter:

• DITA-geleitetes Authoring: FrameMaker liefert spezielle Startpunkte für Task-, Concept- und Reference-Topics. Der Autor sieht eine strukturierte Vorlage und Hinweise, welche Elemente erlaubt sind. Die Software validiert im Hintergrund laufend gegen die DITA-Spezifikation, warnt also sofort, wenn z. B. ein <section> an falscher Stelle eingefügt würde. Attribute lassen sich über Dialoge setzen; z. B. bietet FrameMaker ein Panel, in dem man Profilierungsattribute anhaken kann, statt sie als Code einzugeben.
• Wiederverwendung mittels Keys und Conrefs: FrameMaker vereinfacht das Einfügen von Inhaltsreferenzen (Conrefs) erheblich. Über Menüs kann ein Autor ein externes DITA-Element auswählen und als referenzierten Inhalt ins aktuelle Topic einbinden – FrameMaker zeigt diesen Inhalt dann (mit einer leichten Hintergrundmarkierung) an, als wäre er Teil des Dokuments. Ändert sich die Quelle, aktualisiert FrameMaker die Darstellung. Ähnlich funktioniert der Umgang mit Keys: In einer DITA-Map definierte Schlüssel (z. B. Produktvariablen) kann der Autor via Key-Einfügen nutzen. FrameMaker zeigt im Editor anstelle der abstrakten Key-Referenz bereits den aufgelösten Wert an, wodurch Autoren beim Schreiben den finalen Text sehen. Das reduziert Fehler bei der Verwendung von Variablen. Zusätzlich unterstützt FrameMaker Snippet-Bibliotheken – z. B. kann man häufig benötigte Strukturen (wie ein standardisiertes Warnhinweis-Block) als Vorlage speichern und bei Bedarf abrufen, was dann entweder als statische Kopie oder als Conref eingesetzt wird.
• Publikation über DITA-OT: FrameMaker ist in der Lage, auf Knopfdruck verschiedene Ausgabeformate aus DITA zu erzeugen. Intern greift es dazu auf das DITA Open Toolkit (teils angepasst) zurück, ohne dass der Benutzer dies merken muss. So kann ein Redakteur beispielsweise direkt „Speichern als PDF“ oder „Veröffentlichen als HTML5“ wählen, und FrameMaker orchestriert den Prozess. Die Besonderheit: FrameMaker kann dabei eigene Stylesheets/Templates an das DITA-OT übergeben. So lassen sich z. B. PDF-Ausgaben mit dem Layout-Feinschliff von FrameMaker kombinieren. Für HTML5 liefert FrameMaker ebenfalls Standard-Templates mit, die man aber auch anpassen kann. Im Ergebnis erhält man qualitativ hochwertige Publikationen aus dem Editor heraus, was besonders für kleinere Teams ohne separate Build-Engine attraktiv ist. FrameMaker erlaubt es auch, Bedingungen/Filter für den Publish-Lauf zu setzen (z. B. „erzeuge jetzt die Ausgabe mit audience=Admin“), ohne in die Kommandozeile gehen zu müssen.
• Review-Unterstützung und Qualität: FrameMaker bietet eingebaute Review-Funktionen, die beim Arbeiten mit DITA hilfreich sind. Autoren können Änderungen im Track-Change-Modus durchführen; alle Änderungen werden dann farblich markiert und können später akzeptiert oder verworfen werden – ähnlich wie in Word, aber strukturbewusst. Kommentare können an beliebigen Stellen eingefügt werden, ohne das XML zu verletzen (werden als separate Annotationselemente gehandhabt). Für Team-Reviews lässt sich ein PDF mit Kommentarmöglichkeit erzeugen: Externe Reviewer können im PDF Anmerkungen machen, und FrameMaker kann diese Kommentare wieder importieren und dem jeweiligen Punkt im DITA-Topic zuordnen. Das erleichtert den Review-Prozess erheblich, weil man nicht manuell über zwei Dokumente gehen muss. Zudem hat FrameMaker Funktionen zum Vergleich von Dokumentversionen: Zwei DITA-Dateien können geladen und Unterschiede automatisch hervorgehoben werden – nützlich, um z. B. vor/nach einer Änderung zu sehen, was konkret geändert wurde (gerade bei kleinen Textanpassungen in großen Topics sehr praktisch). All dies trägt zur Qualitätssicherung bei, da Änderungen kontrolliert und Feedback-Schleifen unterstützt werden. Nicht zuletzt prüft FrameMaker beim Öffnen von DITA-Maps auch auf Konsistenz: Es meldet fehlende Grafikdateien, ungültige Querverweise oder ähnliche Probleme, die man so früh beheben kann.

Stärken in Softwareprojekten: Adobe FrameMaker zeigt seine Stärken besonders dort, wo umfangreiche, komplex strukturierte Dokumentationen entstehen – wie oft in Softwareprojekten. Einige Vorteile aus der Praxis: FrameMaker ist bekannt dafür, auch sehr große Dokumente oder Mengen an Topics stabil zu handhaben. Wo andere Editoren oder Textverarbeitungen bei 1000+ Seiten an ihre Grenzen stoßen, kann FrameMaker dank seiner historischen Wurzeln im Buchsatz auch solche Größen bewältigen. Für ein Team, das z. B. eine gesamte Produktdokumentation mit hunderten Topics bearbeitet, ist das ein Zuverlässigkeitsfaktor. Des Weiteren liefert FrameMaker sehr präzise Layout-Kontrolle, was insbesondere bei PDF relevant ist. In Software-Dokus kommen häufig komplexe Elemente vor: vielschachtelige nummerierte Listen, große Tabellen (Konfigurationstabellen, APIs), Code-Blöcke mit besonderer Formatierung, Bildschirmfotos mit Beschriftungen etc. FrameMaker bietet für all dies ausgefeilte Formatierungsfunktionen (z. B. automatischer Zeilenumbruch in Tabellenzellen, fortlaufende Nummerierung über verschachtelte Listen hinweg, Definition von Absatzformaten für Code mit monospace-Schrift etc.). Dadurch sehen die PDFs aus FrameMaker professionell und konsistent aus, ohne dass nachträgliches Layouten nötig ist. Ein weiterer Pluspunkt: FrameMaker unterstützt Conditional Text (Bedingten Text) schon seit jeher – diese Funktion deckt sich weitgehend mit DITA-Profilierung. Für Autoren ist das Ein-/Ausblenden von Varianteninhalten damit sehr intuitiv (per Klick in der Bedingungsleiste). In Softwareprojekten, wo oft viele Bedingungen (verschiedene OS, Editionen, Rollen) eine Rolle spielen, ist dieses visuelle Management Gold wert. Auch die Performance beim Navigieren in modularen Handbüchern ist gut: FrameMaker kann DITA-Maps als sogenannte Composite öffnen, d.h. der Autor sieht das ganze Handbuch in einem aufgespannten Dokument, kann aber dennoch kapitelweise speichern. So hat man sowohl das große Ganze als auch die modulare Einheit im Blick. Nicht zuletzt gibt es in FrameMaker Skript- und Automatisierungsmöglichkeiten (via ExtendScript oder FrameMaker API), was z. B. genutzt werden kann, um wiederkehrende Aufgaben zu erleichtern – etwa Serien-Beschriftungen für alle Abbildungen einzufügen oder Formatvorlagen global zu ändern. Diese technischen Vorteile machen FrameMaker in vielen Software-Unternehmen zum bevorzugten DITA-Tool, vor allem wenn zuverlässige PDF-Ausgabe gefordert ist und die Dokumentation komplex aufgebaut ist.

Grenzen & Best Practices: Trotz der vielen Stärken gibt es auch Grenzen und wichtige Best Practices beim Einsatz von FrameMaker für DITA. Eine Grenze liegt in der Trennung von Inhalt und Layout: FrameMaker ist so mächtig, dass Autoren theoretisch jedes Layoutdetail beeinflussen könnten – das verführt manchmal dazu, inhaltliche Arbeit mit Formatarbeit zu vermischen (z. B. manuell Abstände einzufügen, individuelle Formatübersteuerungen vorzunehmen). Dies kann kontraproduktiv sein, wenn die Publikation später vielleicht auch ohne FrameMaker (z. B. nur via DITA-OT auf einem Server) erfolgt. Best Practice ist daher, so strikt wie möglich bei der strukturierten Arbeitsweise zu bleiben: Formatierungen nur über Vorlagen, keine manuellen Fonts, keine lokalen Einzüge etc. FrameMaker sollte im Grunde als strukturierter Editor benutzt werden, nicht als frei gestaltbares DTP-Tool, wenn man DITA einsetzt. Weiterhin sollte man klare Namenskonventionen innerhalb FrameMaker einhalten: z. B. für bedingte Texte (die FrameMaker-intern mit farbigen Tags benannt werden) dieselben Begriffe verwenden wie im DITA-Profil, damit es nicht zu Verwirrungen kommt. FrameMaker erlaubt einige Dinge, die DITA nicht direkt kennt (z. B. sog. Text Insets oder Unstructured-Sections) – solche Funktionen sollte man meiden oder wissen, wie sie sich beim XML-Speichern verhalten. Ein potenzieller Stolperstein ist auch das Versionsmanagement: FrameMaker funktioniert sehr gut mit linearen Bookfiles, aber im DITA-Kontext arbeitet man ja oft dateibasiert mit Git. Hier ist Best Practice, nicht mehrere Autoren gleichzeitig dieselbe Datei in FrameMaker bearbeiten zu lassen (das würde Merge-Konflikte bringen), sondern vorher zu locken oder sich abzustimmen – oder ein CCMS mit Checkout-Funktion zu nutzen. Für die Profilierungsregeln gilt: Weniger ist mehr, wie auch bei den vorherigen Beispielen gesehen. FrameMaker macht es zwar einfach, zig Bedingungen zu definieren (man kann farbige Tags anlegen so viele man will), aber im Sinne der Wartbarkeit sollte das Team sich auf einen Kanon einigen (z. B. genau diese 5 Profilattribute verwenden, feste Farbkennung, dokumentierte Kombinationen). Ein Styleguide sollte auch FrameMaker-spezifische Tipps enthalten, z. B. „Wie markiere ich etwas als optionalen Schritt“ – FrameMaker kann dafür Conditional Text „optional“ nutzen, aber jeder muss das einheitlich tun. Schließlich zur CI-Integration: FrameMaker wird von manchen Teams primär interaktiv genutzt und die finale Veröffentlichung dann via Skript/Server mit DITA-OT gemacht. Hier ist wichtig, die Kompatibilität sicherzustellen. Best Practice: dieselben DITA-OT-Versionen und Plugins, die FrameMaker intern nutzt, auch auf dem Build-Server einzusetzen. Und keine proprietären FrameMaker-Features (wie spezielle Prozessanweisungen) zu verwenden, die außerhalb des Tools nicht interpretiert werden. So bleibt gewährleistet, dass ein Build in der Pipeline das gleiche Ergebnis liefert wie ein „Publish“ aus dem Desktop-Tool. In Summe lässt sich sagen: FrameMaker ist ein kraftvolles Werkzeug im DITA-Kontext, das aber – wie ein Sportwagen – auch verantwortungsvoll gefahren werden will. Mit klaren Richtlinien und etwas Disziplin entfaltet es seine Vorteile, ohne die Konsistenz der strukturierten Inhalte zu beeinträchtigen.

6. Beratung zur Einführung und Weiterentwicklung von DITA-Szenarien mit Adobe FrameMaker

Die Einführung von DITA in einem Unternehmen – insbesondere in Kombination mit Tools wie Adobe FrameMaker – ist ein strategisches Vorhaben. Eine Beratungsleistung kann hier helfen, Fehler zu vermeiden und schneller produktiv zu werden. Im Folgenden wird skizziert, wie eine solche Beratung aussehen kann, welche Leistungen sie umfasst, wie ein typisches Vorgehensmodell in Phasen abläuft und welche Kennzahlen sowie Ergebnisse dabei im Fokus stehen.

Leistungsumfang: Eine spezialisierte DITA-Beratung bietet in der Regel ein Rundum-Paket, das sowohl konzeptionelle Aspekte als auch technische Umsetzung abdeckt. Typische Bestandteile sind:

• Assessment & Roadmap: Zunächst wird der Ist-Zustand erfasst. Die Berater analysieren vorhandene Inhalte (Formate, Umfang, Sprachen), eingesetzte Tools, bestehende Prozesse (Freigaben, Übersetzung, Publikation) und identifizieren Pain Points. Daraus wird ein Zielbild entwickelt – wie könnte die Dokumentationslandschaft mit DITA aussehen? – sowie eine schrittweise Roadmap. Diese enthält Quick-Wins (Maßnahmen, die schnell Nutzen bringen, z. B. bestimmtes Handbuch zuerst umstellen) und Meilensteine. Ziel ist, dass der Kunde eine klare Entscheidungsgrundlage hat, was die Einführung bringt und wie er vorgehen kann.
• Informationsarchitektur: In dieser Phase entwirft die Beratung zusammen mit dem Kundenteam das zukünftige Inhaltsmodell. Welche Topic-Typen werden benötigt (Standard Task/Concept/Reference reichen meist, aber evtl. Specials wie Troubleshooting-Topic)? Wie sollen Topics zugeschnitten sein (Granularität)? Man erarbeitet eine sinnvolle Modularisierungsstrategie: z. B. Zerlegung nach Produktkomponenten, nach Dokumentationsarten (Install, User Guide, API etc.). Es entsteht eine Art Dokumenten-Taxonomie und Strukturplan. Zudem wird definiert, wie Wiederverwendung konzeptionell erfolgen soll (Identifikation redundanter Inhalte, Planung von Snippets/Conrefs, Einsatz von Key-Principles). Dieser Architekturentwurf ist essenziell, bevor man mit Migration oder Tool-Einstellungen startet.
• Styleguides & Bausteinbibliothek: Parallel dazu (oder anschließend) unterstützt die Beratung beim Aufsetzen von Redaktionsleitfäden und Templates. Ein DITA-Styleguide hält z. B. fest: Schreibregeln, Terminologie-Vorgaben, Do’s & Don’ts in der Verwendung der neuen Struktur (z. B. „Konzept-Topics dürfen keine prozeduralen Schritte enthalten“). Außerdem wird eine Bausteinbibliothek angelegt – das sind vorgefertigte Module für häufige Inhalte, etwa standardisierte Warnhinweise, sich wiederholende Prozeduren, Formatierungsbeispiele für GUI-Elemente usw. Diese Bibliothek beschleunigt die Arbeit der Redakteure später erheblich und fördert Konsistenz. Ebenfalls Teil dieser Phase: Terminologie-Arbeit (ggf. Glossar in DITA anlegen) und die Definition von Variablen/Keys für wiederkehrende Produktnamen oder Texte.
• Toolchain & Automation: Hier geht es um die technische Umsetzung. Die Berater richten Adobe FrameMaker für die DITA-Nutzung optimal ein: z. B. Anpassung der Templates (FrameMaker EDD) an die Corporate Identity, Laden passender DITA-OT-Plugins, Konfiguration der Publikationsprofile (für HTML5, PDF etc.). Es wird eine Build-Umgebung eingerichtet – typischerweise ein Build-Skript oder -Server, der DITA-OT ansteuert, mit Parametern für verschiedene Ausgaben. Bei Bedarf wird auch ein CCMS (Component Content Management System) empfohlen oder integriert, je nach Größenordnung des Contents. Die Automation umfasst auch CI-Integration: Die Beratung kann helfen, DITA-Publikationen in bestehende Continuous Integration (z. B. Jenkins Pipelines) einzubinden, sodass z. B. jede Nacht oder bei jedem Commit die Doku neu erzeugt wird. Außerdem werden Tools für Qualitätsprüfungen eingebunden (z. B. Linting-Tools für DITA, Spellchecker, Linkchecker), damit die Content-Qualität automatisch überwacht wird.
• Übersetzungsvorbereitung: Ein DITA-Consultant achtet darauf, dass die Weichen für Lokalisierung richtig gestellt sind. Das bedeutet: Die Struktur muss übersetzungsfreundlich sein (keine unnötigen Sätze trennen, keine komplexen Verschachtelungen, die Übersetzung erschweren). Terminologie muss festgezogen werden, bevor übersetzt wird (ein Wort – ein Begriff). Man legt Prozesse fest, wie Inhalte an Übersetzer gehen – ob via XLIFF, Schnittstellen zu Translation-Memory-Systemen oder manuelle Exporte. Ziel ist es, dass DITA nahtlos mit Übersetzungsdienstleistern funktioniert und Übersetzungsvolumen reduziert wird (durch Reuse und Konsistenz). Die Beratung kann auch helfen, bestehende Translation Memorys zu nutzen, indem initiale Übersetzungen der DITA-Topics mit vorhandenen Sätzen vorgefüllt werden (Mapping alter Dokumente auf neue Segmente, soweit möglich).
• Pilot & Rollout: Statt sofort alles umzustellen, wird empfohlen, einen Pilotbereich zu definieren. Die Beratung begleitet die Umsetzung eines Pilotprojekts – z. B. ein bestimmtes Handbuch oder ein Teil der Doku wird mit DITA neu aufgesetzt. Dabei wird das Team geschult und sammelt Erfahrungen. Die Berater helfen operativ bei der Migration von Inhalten (Konvertierung aus Word, Wiki, was vorhanden ist, nach DITA – teil-automatisiert durch Scripts oder manuell, je nach Qualität der Alt-Daten). Am Ende der Pilotphase stehen greifbare Ergebnisse: eine kleine DITA-Dokumentation mit realem Inhalt, erzeugt via FrameMaker/DITA-OT, sowie ein verfeinerter Styleguide basierend auf den Lessons Learned. Wichtig: Mit dem Pilot werden auch KPI-Baselines gemessen (z. B. wie lange brauchten wir für X Seiten, welche Wiederverwendungsrate haben wir erreicht?), um den Fortschritt im späteren Rollout sichtbar zu machen.
• Betrieb & Weiterentwicklung: Nach dem Rollout (siehe Vorgehensmodell unten) endet die Beratung nicht abrupt. Gute Beratungsangebote sehen eine Hypercare-Phase vor: In den ersten Monaten des produktiven Einsatzes steht man für Support und Nachsteuerung bereit. Man hilft, Prozesse zu stabilisieren, z. B. regelmäßige Publikationen zuverlässig hinzubekommen, Anwenderfragen zu klären, eventuell weitere Automatisierungen nachzurüsten. Außerdem wird gemeinsam ein Plan für die kontinuierliche Verbesserung erstellt: DITA-Projekte profitieren von iterativer Optimierung – sei es, dass man neue DITA-OT-Versionen mit verbesserten Features einspielt, sei es, dass man weitere Dokumentationsarten integriert (z. B. Online-Hilfe, API-Doku, wenn anfangs nur Handbücher gemacht wurden). Die Beratung unterstützt also nicht nur beim Setup, sondern auch dabei, dass das System im Betrieb lebt und sich an veränderte Anforderungen anpasst (z. B. neue Normen, neue Plattformen, wachsende Inhalte).

Vorgehensmodell (Phasen & Ergebnisse): Typischerweise gliedert sich ein DITA-Einführungsprojekt in mehrere Phasen:

1. Phase 1 – Analyse (2–4 Wochen): In dieser initialen Phase wird der Grundstein gelegt. Ergebnis ist ein Audit-Bericht des Ist-Zustands, eine klare Definition der Ziele (z. B. „50% Redundanzabbau, Publikation 1 Woche schneller“), sowie eine priorisierte Liste von Anforderungen und ToDos. Oft entsteht auch schon ein grober Proof-of-Concept-Plan: Also welches kleine Set an Inhalten nimmt man für den Pilot, um das Konzept zu beweisen.
2. Phase 2 – Pilot (4–8 Wochen): Nun wird das in kleinerem Maßstab umgesetzt. Ergebnisse dieser Phase: Ein migrierter Inhaltsbestand (z. B. ein Kapitel oder Handbuch) in DITA, konfiguriertes FrameMaker mit DITA-Umgebung, erste Ausgabe via DITA-OT (HTML/PDF) erzeugt. Außerdem ein Styleguide v1 und die initiale Snippet-Bibliothek. Ebenfalls wird hier oft schon ein KPI-Baseline-Report erstellt – z. B. man misst, wie viele Topics erstellt, wie viel wiederverwendet etc., als Ausgangswert.
3. Phase 3 – Rollout (8–16 Wochen): Die große Rollout-Phase skaliert den Pilot auf den gesamten vorgesehenen Umfang. Inhalte der gesamten Dokumentation (oder definierter Produktlinien) werden nach DITA überführt, zusätzliche Teammitglieder werden geschult und eingebunden. Bibliotheken und Templates werden finalisiert und „produktiv gestellt“. Die CI-Builds laufen jetzt für alle relevanten Outputs regelmäßig. Der Übersetzungsworkflow wird komplett implementiert (alle Sprachen, alle Inhalte). Am Ende dieser Phase ist das neue System live: die Dokumentationen werden nun aus DITA/FrameMaker erzeugt. Es erfolgen Abnahmen, ggf. Audits, ob alle Anforderungen erfüllt sind.
4. Phase 4 – Betrieb (laufend): Nach dem Rollout geht das Projekt in den Normalbetrieb über. Die Beratung begleitet dies oft für einige Zeit (z. B. 3-6 Monate) mit regelmäßigen Check-ins. In dieser Phase werden Prozesse gefestigt: z. B. es werden neue Teammitglieder on-boarded mit Schulungen, es werden Wartungsroutinen etabliert (z. B. vierteljährlich DITA-OT-Update prüfen, Terminologie-Review usw.). KPI-Reviews finden statt – also Messung und Vergleich der Kennzahlen gegen die Baseline, um Erfolg nachzuweisen oder nachzujustieren. Änderungen am System (neue Features, geänderte Anforderungen) werden aufgenommen und geplant. Diese Phase geht dann in einen kontinuierlichen Verbesserungsprozess über, wo das Unternehmen selbst oder mit gelegentlicher Beratung das System weiter pflegt.

Kennzahlen & Kontrolle: Wie bereits erwähnt, werden in solchen Projekten oft KPIs genutzt, um Erfolg und Fortschritt zu tracken. Einige wichtige Kennzahlen sind:

• Wiederverwendungsquote (%): Vor und nach DITA wird gemessen, wie viel Content redundant ist. Ein Ziel könnte sein, diese Quote von z.B. 30% auf 60% zu steigern (d.h. 60% aller Inhalte werden mehrfach genutzt). Jeder Prozentpunkt mehr bedeutet weniger Erstellungs- und Übersetzungsaufwand.
• Time-to-Publish: Die Zeit zwischen Fertigstellung der Software und Fertigstellung der Doku. Hier will man Reduktion sehen – etwa von 10 Tagen auf 2 Tage. Gerade Leitung Technische Redaktion und Produktmanagement achten darauf, weil schnellere Doku Veröffentlichung Marktchancen verbessern kann.
• Übersetzungsumfang (Wörter): Pro Release oder pro Jahr kann man zählen, wie viele Wörter neu/geändert zur Übersetzung gehen. Durch DITA sollte dieser Wert sinken oder langsamer steigen als der Funktionsumfang. Eine Kennzahl könnte sein: pro Release maximal 20% neue Übersetzungswörter, 80% Wiederverwendung aus TM.
• Fehlerdichte: z. B. dokumentationsbezogene Fehler oder Nachbesserungen pro Ausgabe. Wenn z. B. vorher in jedem Release 15 Doku-Bugs gemeldet wurden und nach Einführung nur noch 5, ist das ein messbarer Erfolg. Diese Zahl ist auch für Qualitäts- und Compliance-Verantwortliche relevant.
• Review-Durchlaufzeiten: Wie lange dauert ein Review-Zyklus für eine Doku? Mit DITA parallelisieren sich Reviews, und diese Kennzahl sollte sinken. Beispiel: Ein komplettes Handbuch-Review dauerte früher 4 Wochen mit 5 Reviewern sequentiell, jetzt werden Topics parallel in 1 Woche von allen geprüft.

Diese Kennzahlen werden meist in einem Projektcockpit verfolgt und regelmäßigen Stakeholdern berichtet. So sieht das Management, ob die Investition in DITA/FrameMaker den gewünschten Effekt bringt. Bei Abweichungen (z. B. Wiederverwendungsquote steigt nicht wie erhofft) kann gezielt nachgesteuert werden (vielleicht doch mehr Snippets anlegen, etc.).

Typische Ergebnisse: Wenn DITA mit Unterstützung richtig eingeführt wird, zeigen sich mehrere positive Ergebnisse:

• Konsistente Dokumente: Durch standardisierte Strukturen und Terminologie sieht die gesamte Dokumentation aus „einem Guss“ aus. Unstimmigkeiten zwischen Kapiteln oder unterschiedlichen Autoren verschwinden weitgehend. Das erhöht die Leserzufriedenheit und verringert Missverständnisse.
• Kürzere Publikationszyklen: Unternehmen können ihre Doku nun schneller aktualisieren. Aus Wochen werden Tage oder Stunden. Das erlaubt z. B. häufiger Updates an Online-Dokumentation (viele Softwarefirmen gehen zu Continuous Documentation über – analog zur Continuous Delivery der Software).
• Niedrigere Übersetzungskosten: Viele Organisationen berichten nach DITA-Einführung von signifikanten Einsparungen beim Lokalisierungsbudget. Weniger Volumen, bessere TM-Ausnutzung und konsistente Quellen machen es möglich. Zudem kann man durch den modularen Ansatz auch Übersetzungen priorisieren (z. B. zuerst wichtige Topics, dann der Rest), was Flexibilität schafft.
• Bessere Nachvollziehbarkeit über Releases: Mit DITA und einem systematischen Vorgehen lässt sich lückenlos nachvollziehen, was sich in welcher Version geändert hat. Historische Stände können bei Bedarf wieder ausgegeben werden. Für Compliance-Prüfungen (etwa in regulierten Branchen) ist das ein großer Vorteil, da man zeigen kann, dass jede Änderung kontrolliert und dokumentiert wurde.
• Höhere Produktivität des Doku-Teams: Indirekt messbar, aber spürbar: Redakteure verbringen weniger Zeit mit Suchen, Kopieren, Formatieren und mehr Zeit mit inhaltlicher Arbeit. Das steigert die Qualität und den Wert der Dokumentation. Es trägt auch zur Motivation bei – das Team kann sich als „Wissensmanager“ statt „Textschubser“ sehen, weil viel Routine durch Tools abgenommen wird.

Zusammengefasst ergibt eine professionelle Beratung einen ganzheitlichen Ansatz: von der Idee bis zur laufenden Nutzung. Sie hilft, Risiken (z. B. falsche Struktur, Toolprobleme) zu minimieren und Best Practices umzusetzen, die sich andernorts bewährt haben.

7. Checklisten & Vorlagen (kompakt, sofort nutzbar)

Im Folgenden sind einige Checklisten und Vorlagen aufgeführt, die sofort in der Praxis angewendet werden können. Sie fassen Kernelemente der vorher besprochenen Themen kompakt zusammen und dienen als Leitfaden für die Implementierung von DITA und FrameMaker in Ihrem Software-Dokumentationsprojekt.

Checkliste Informationsarchitektur (Top 10 Punkte)

1. Zielgruppen & Doku-Typen definieren: Klären Sie, wen Sie adressieren (Endbenutzer, Admin, Entwickler etc.) und welche Doku-Artefakte benötigt werden (Handbuch, API-Guide, Hilfe…). Daraus ergeben sich Anforderungen an Struktur und Detailtiefe.
2. Topic-Typen & Vorlagen festlegen: Bestimmen Sie, welche DITA-Topic-Typen zum Einsatz kommen und wofür. Legen Sie z. B. fest: Task für Verfahrensanweisungen, Concept für Hintergrundinfos, Reference für Parameterlisten. Erstellen Sie Template-Dateien, damit neue Topics diese Struktur automatisch haben.
3. Granularität abstimmen: Definieren Sie eine sinnvolle Topic-Größe. Faustregel: Ein Topic behandelt ein einzelnes Thema oder Use-Case. Lieber mehr kleine Topics als wenige riesige. Prüfen Sie Ihre Inhalte: Wo neue Überschriften im Text vergeben wurden, sind oft Schnitte für eigenständige Topics geeignet.
4. Wiederverwendungspotenziale identifizieren: Analysieren Sie vorhandene Inhalte auf Duplikate. Markieren Sie Bereiche, die in mehreren Publikationen vorkommen (z. B. gleiche Sicherheitshinweise, identische Schritte). Planen Sie, diese als separate wiederverwendbare Topics oder Snippets vorzusehen, statt sie mehrfach zu schreiben.
5. Struktur der Ablage entwerfen: Entwickeln Sie eine konsistente Ordnerstruktur für Ihr Content-Repository. Möglichkeiten: nach Produktbereichen (z. B. Ordner „Installation“, „Konfiguration“), nach Dokumenttypen (Ordner „UserGuide“, „AdminGuide“) oder eine Mischung. Wichtig ist, dass Autoren Inhalte logisch finden und Ablageorte klar definiert sind.
6. Namenskonventionen für Dateien und IDs: Legen Sie fest, wie DITA-Dateien benannt werden. Empfehlung: sprechende Dateinamen in Englisch, alles klein und ohne Leerzeichen (z. B. install_win_task.dita). Verwenden Sie Präfixe/Suffixe für bestimmte Typen (etwa _concept, _task im Namen) zur schnellen Erkennbarkeit. Auch für IDs innerhalb von Topics eine Konvention einführen (z. B. <topic id=“prodX_install_win“>).
7. Taxonomie und Metadaten: Entwickeln Sie eine einfache Taxonomie zur Kategorisierung der Topics (z. B. Tags für Modul, Zielgruppe, Schwierigkeitsgrad). Überlegen Sie, welche Metadaten pro Topic erfasst werden sollen – etwa Produktversion, Autor, Prüfer, Gültigkeitsdatum. Diese helfen bei Filterung, Suche und Dokumentenkonformität.
8. Varianten- und Versionsstrategie: Entscheiden Sie, wie Sie Produktvarianten (Editionen, Plattformen, Kundenversionen) und Versionen managen. Definieren Sie, welche Profilierungsattribute genutzt werden (z. B. product, platform, audience) und vermeiden Sie Überschneidungen. Planen Sie, ab welcher Abweichung lieber separate Topics/Maps verwendet werden, statt das gleiche Topic mit zu vielen Bedingungen zu überfrachten.
9. Integration Entwicklungsprozess: Stellen Sie sicher, dass die Informationsarchitektur mit dem Softwareprozess zusammenspielt. Z.B. definieren Sie, wie neue Features dokumentiert werden (vielleicht pro Feature ein Topic, das in einer Release-Map verlinkt wird). Schaffen Sie ggf. Verknüpfungen (z. B. Ticket-IDs als Meta in Topics), um Traceability zu erreichen.
10. Dokumentation der Architektur: Halten Sie all diese Entscheidungen schriftlich fest in einem Informationsarchitektur-Dokument. Erläutern Sie die Struktur, geben Sie Beispiele. Schulen Sie das Team darauf, sodass alle Beteiligten – Redakteure, Entwickler, Übersetzer – das Konzept verstehen und einheitlich umsetzen.

Profilierungsrichtlinien (Do’s & Don’ts)

Do’s – Empfohlene Vorgehensweisen bei Profilierung:

• Gezielt einsetzen: Verwenden Sie Profilierung nur dort, wo wirklich unterschiedliche Ausgaben nötig sind. Beispielsweise für echte Produktvarianten (Module an/aus) oder verschiedene Benutzerrollen. Halten Sie die Logik klar – der Leser sollte am Ende eindeutig wissen, in welcher Version welcher Inhalt gilt.
• Konsistente Attribute: Legen Sie einen festen Satz an Profilierungsattributen und -werten fest (z. B. platform = {windows, linux}, audience = {admin, user}). Nutzen Sie diese konsequent und vermeiden Sie ständige Neuerfindungen. Dokumentieren Sie, was jeder Wert bedeutet.
• Sparsam kombinieren: Wenige, übersichtliche Profilierungsbedingungen sind besser als hochgradig verschachtelte. Wenn möglich, kombinieren Sie Bedingungen statt separate Flags zu erstellen. Z. B. anstatt separate Attribute „enterprise“ und „cloud“ zu nutzen und beide zu kombinieren, erwägen Sie ein Attribut edition={std, enterprise_cloud, enterprise_onprem} – sofern das die Fälle vereinfacht.
• Testen Sie Filter-Ausgaben: Richten Sie für jede gängige Profil-Kombination (z. B. Sprache=DE + Edition=Standard + Platform=Windows) ein Test-Build ein. Vergewissern Sie sich, dass keine Lücken oder unerwarteten Texte auftreten. Regelmäßige Probedurchläufe stellen sicher, dass die Bedingungen korrekt greifen.
• Attribute statt separate Dateien: Wenn Änderungen klein und gezielt sind, nutzen Sie lieber Profilattribute innerhalb desselben Topics, anstatt den kompletten Topic zu duplizieren. So bleiben Updates an gemeinsamen Teilen zentral. Beispiel: Ein Kommando unterscheidet sich unter Linux vs Windows nur in einem Parameter – steuern Sie diesen Satz per platform-Attribut, statt zwei fast identische Topics zu pflegen.

Don’ts – Was vermieden werden sollte:

• Profilierung als Allheilmittel: Benutzen Sie Profilierung nicht, um grundverschiedene Inhalte in ein Topic zu zwingen. Wenn zwei Varianten eines Kapitels völlig anders aussehen, trennen Sie sie lieber in eigene Topics/Maps. Zu viel Bedingung im Text verwirrt Autoren und Reviewer – und birgt Risiko, dass am Ende Zusammenhänge fehlen.
• Überlappende Bedingungen: Vermeiden Sie es, mehrere verschiedene Attribute für denselben Zweck zu verwenden. Z. B. nicht zwei Attribute audience und role parallel pflegen, wenn beide im Grunde das Gleiche ausdrücken. Das führt zu Chaos (was, wenn audience=admin aber role=user?). Definieren Sie klar, welches Attribut wann zum Einsatz kommt.
• Unnötige Kleinteiligkeit: Markieren Sie nicht jedes Wort oder jeden Satz mit Bedingungen, wenn es auch ohne geht. Beispiel: Statt zwei Worte in einem Satz auszublenden („Klicken Sie auf Start [Pro-Version: und wählen Sie X]“), überlegen Sie, ob der ganze Abschnitt für Standardnutzer sinnvoll ist. Zu fragmentierte Bedingungsblöcke machen die Wartung schwer.
• Profil-„Leichen“ lassen: Über die Zeit können Bedingungen obsolet werden (z. B. ein bestimmter Wert wird nicht mehr genutzt). Entfernen Sie solche konsequent aus dem Content und aus den Ditaval-Dateien. Alte, ungenutzte Profilierungen führen zu Verwirrung und bergen die Gefahr, dass jemand versehentlich falsche Einstellungen wählt.
• Manual Overrides statt Ditaval: Versuchen Sie nicht, Profilierungen „manuell“ durch mehrere Output-Dateien zu steuern (z. B. indem Sie händisch Texte an- und ausschalten). Nutzen Sie stets strukturierte Ditaval-Dateien und Build-Skripte, um Varianten zu erzeugen. So ist reproduzierbar, welche Filter gesetzt waren, und das Risiko menschlicher Fehler sinkt.

Beispiel-Ordnerstruktur & Dateibenennung

Eine sinnvolle Organisation Ihrer DITA-Projektdateien hilft allen Teammitgliedern, Inhalte schnell zu finden und ordentlich zu halten. Hier ein Beispiel einer Ordnerstruktur und Benennungskonvention für ein Softwaredoku-Projekt:

• /docs (Hauptordner des Dokumentationsprojekts)
• /topics (enthält alle DITA-Topic-Dateien, meist weiter untergliedert)
  • /installation – z. B. alle Topics rund um Installation und Setup
  • install_requirements.dita (Systemvoraussetzungen, Concept)
  • install_windows_task.dita (Installationsanleitung Windows, Task)
  • install_linux_task.dita (Installationsanleitung Linux, Task)
  • …
  • /configuration – alle Topics zur Konfiguration/Administration
  • config_database_task.dita
  • user_management_task.dita
  • concept_security.dita
  • …
  • /reference – ggf. separate Ablage für Referenztabellen, API-Doku etc.
  • api_endpoints_reference.dita
  • error_codes_reference.dita
• /maps (enthält DITAMap-Dateien, die die Publikationen definieren)
  • UserHandbuch.ditamap (German User Handbook Map)
  • UserHandbook_en.ditamap (English User Handbook Map)
  • AdminGuide.ditamap etc.
  • ReleaseNotes_Q1_2025.ditamap (Map für Release-Notes eines Releases)
• /keys (optionaler Ordner für Key-Definitionen, falls separiert)
  • productNames.ditamap (enthält Schlüssel für Produkt-/Firmennamen)
  • ui_strings.ditamap (Schlüssel für UI-Begriffe)
• /images (Grafiken/Screenshots, ggf. weiter in Unterordner pro Kapitel)
  • login_screen.png
  • settings_dialog_de.png etc.
• /output (wird oft nicht im Repo versioniert, aber lokal für Builds benutzt)
  • /pdf, /html, … (hier landen generierte Dateien zur Ansicht)

Dateibenennungsregeln:
– Verwenden Sie englische, beschreibende Dateinamen für Topics, unabhängig von der Sprache des Inhalts. Das erleichtert global die Orientierung (z. B. weiß jeder im Team, was backup_schedule_task.dita ungefähr enthält).
– Keine Leer- oder Sonderzeichen: Trennen Sie Worte mit Bindestrich – oder Unterstrich _. Umlaute und ß vermeiden (ae statt ä, etc.), damit es keine Encoding-Probleme gibt.
– Topic-Typ andeuten: Optional kann der Typ ans Ende, z. B. _concept, _task, _ref. Im Beispiel oben sieht man das – es hilft beim Öffnen mit Tools, weil FrameMaker/Oxygen oft aus dem Dateinamen den initialen Topic-Typ ableitet.
– Kürzel für Sprachen: Falls Sie mehrere Sprachversionen als eigenständige Dateien führen (nicht empfohlen bei DITA, aber falls doch), nutzen Sie ISO-Sprachcodes als Suffix. Z. B. Guide_de.ditamap für deutsch, Guide_en.ditamap für englisch. In einer Single-Source mehrsprachigen DITA aber eher durch Profile gesteuert, daher selten separate Dateien pro Sprache nötig.
– Versionsstände: Für lebende Dokumente pflegt man i.d.R. keine Versionsnummer im Dateinamen, sondern steuert das über Branches/Ordner. Wenn allerdings z. B. einzelne Dateien versioniert parallel existieren müssen, kann man eine Versionsnummer anhängen (z. B. _v2 im Namen). Allerdings lieber vermeiden – sauberer sind eigene Verzeichnisse pro Version.

Wichtig ist, dass diese Konventionen dokumentiert und allen Autoren bekannt sind. Ein konsistentes Schema vermeidet Chaos und erleichtert automatisierte Verarbeitung (z. B. Skripte können erkennen, dass alles mit _task.dita ein Task-Topic ist usw.).

Minimaler DITA-OT-Build-Leitfaden (Schritte, Parameter, Artefakte)

Die folgenden Schritte beschreiben, wie Sie einen einfachen Build-Prozess mit dem DITA Open Toolkit (DITA-OT) einrichten und ausführen. Dies gilt sowohl für lokale Tests als auch als Basis für eine CI-Integration:

1. DITA-OT installieren: Laden Sie die aktuelle Version des DITA Open Toolkit von dita-ot.org herunter. Entpacken Sie das ZIP an einen festen Ort (z. B. C:\DITA-OT oder /opt/dita-ot). Stellen Sie sicher, dass eine passende Java-Version installiert ist, da DITA-OT als Java-Anwendung läuft.
2. Umgebungsvariable setzen (optional): Für Komfort können Sie die Umgebungsvariable DITA_OT_HOME auf den Installationspfad setzen. Ebenso den PATH erweitern um %DITA_OT_HOME%/bin (Windows) bzw. $DITA_OT_HOME/bin (Linux), damit der Befehl dita überall verfügbar ist.
3. Build-Konfiguration vorbereiten: Wechseln Sie in Ihr Dokumentationsprojekt. Identifizieren Sie die zentrale DITA-Map für die Publikation, die Sie erstellen möchten (z. B. UserHandbook_en.ditamap). Erstellen Sie ggf. eine Ditaval-Datei für Profilfilter (z. B. enterprise.ditaval), falls Sie Inhalte aus-/einblenden müssen. Diese Ditaval ist eine XML, die angibt, welche Profilwerte eingeschlossen/ausgeschlossen werden.
4. Build-Befehl ausführen: Öffnen Sie ein Terminal/Kommandofenster im Projektordner. Führen Sie den DITA-OT-Befehl mit entsprechenden Parametern aus. Zum Beispiel für eine HTML5-Ausgabe:

dita -i UserHandbook_en.ditamap -f html5 -o output/html5 -filter enterprise.ditaval

Erklärung der Parameter:
-i (input) gibt die Eingabe-DITAMap an.
-f (format) wählt das Ausgabeformat, hier html5. (Alternativen: pdf2 für PDF via XSL-FO, pdf5 für PDF via CSS, eclipsehelp, troff, etc.)
-o (outputdir) legt den Ausgabeordner fest, hier output/html5. Dieser sollte existieren oder wird angelegt; dort finden Sie nachher die Ergebnisse.
-filter optional, wendet die genannte Ditaval an (hier z. B. werden nur Inhalte generiert, die in der Enterprise-Version sichtbar sein sollen).

Ohne -filter erzeugen Sie die Standardausgabe mit allem Inhalt. 5. Ausgabe prüfen: Nach erfolgreich durchgelaufenem Build (die Konsole zeigt Warnungen/Errors an, achten Sie darauf) finden Sie im Ausgabeordner die generierten Dateien. Bei HTML5 z. B. eine index.html und Unterordner für Themen, bei PDF direkt die PDF-Datei. Öffnen Sie die Datei(en) und prüfen Sie stichprobenartig, ob alles passt (Formatierung, alle Bilder da, Sonderzeichen ok). Sollten Fehler aufgetreten sein (z. B. „File not found“ für eine Grafik), beheben Sie diese im DITA-Quellmaterial und führen den Build erneut aus. 6. Build anpassen/optimieren: Passen Sie bei Bedarf Parameter oder Styles an. Beispielsweise können im config/-Ordner des DITA-OT weitere Einstellungen vorgenommen werden (Toc-Maximum-Tiefe, Index einschalten etc.), oder Sie nutzen Plugin-Mechanismen, um das Layout zu verändern. Für einen Minimalleitfaden kann dieser Schritt entfallen – das Default-Layout ist oft ein guter Ausgangspunkt. 7. Automatisieren: Um regelmäßig zu publizieren, integrieren Sie den obigen Befehl in ein Skript oder CI-Job. Unter Jenkins z. B. legen Sie einen Build-Step an, der das Repository auscheckt und dann den dita-Befehl ausführt. Verwenden Sie Variablen für unterschiedliche Outputs (z. B. Parameter für Sprache oder Edition), um denselben Job mehrfach für verschiedene Konfigurationen laufen zu lassen. Dokumentieren Sie die Build-Schritte im Projekt-Wiki, damit jeder im Team den Prozess nachvollziehen kann.

Mit diesem einfachen Leitfaden können Sie schnell eigene Builds erzeugen. Natürlich lässt sich DITA-OT sehr weitreichend konfigurieren (z. B. eigenes PDF-Layout mittels XSLT/CSS, verschiedene Output-Plugins installieren usw.), doch für den Einstieg demonstriert obiges Vorgehen den Grundsatz: eine Quelle, viele Ausgabemöglichkeiten.

Review-Checkliste (Inhalt, Struktur, Terminologie, Layout)

Bevor ein DITA-Dokument veröffentlicht wird (sei es ein einzelnes Topic oder ein komplettes Handbuch), sollte es einen Review durchlaufen. Die folgende Checkliste hilft Redakteuren und Fachexperten, systematisch alle relevanten Aspekte zu prüfen:

• Inhalt: Sind die Informationen fachlich korrekt und vollständig? Überprüfen Sie Schritt-für-Schritt-Anleitungen praktisch, ob sie zum gewünschten Ergebnis führen. Fehlen wichtige Hinweise oder gibt es unnötige Wiederholungen? Achten Sie auch auf Aktualität: Beziehen sich alle Beschreibungen auf die aktuelle Softwareversion (z. B. Menübezeichnungen, Parameter)? Jeder neue oder geänderte Feature-Bereich sollte in der Doku reflektiert sein.
• Struktur: Entspricht die Dokumentation dem vorgesehenen Informationsmodell? Prüfen Sie, ob Topic-Typen korrekt eingesetzt wurden (kein Roman im Task-Topic, keine Anleitung im Concept-Topic usw.). Ist die Hierarchie logisch (Überschriftenebenen nicht übersprungen, Unterthemen am richtigen Platz)? Stellen Sie sicher, dass Verlinkungen funktionieren und sinnvoll gesetzt sind: Kreuzverweise zwischen Topics sollten den Leser unterstützen, nicht in Sackgassen führen. Falls Relationen in Maps definiert sind (siehe „related links“), checken Sie, ob diese passend sind. Insgesamt sollte der rote Faden erkennbar sein – falls ein Abschnitt unmotiviert wirkt, könnte er falsch einsortiert sein.
• Terminologie: Wird die festgelegte Terminologie konsistent verwendet? Gleiche Objekte/Funktionen müssen überall gleich benannt sein. Nutzen Sie ggf. ein Terminologietool oder suchen Sie manuell nach Synonymen, die nicht erlaubt sind. (Beispiel: Im ganzen Dokument sollte ein Feld entweder immer „Benutzername“ oder immer „Login“ heißen, nicht beides wechselnd.) Achten Sie auf Anrede und Sprachstil: Im Deutschen meist Sie-Form in der technischen Doku – kein Wechsel zu Du oder Passiv unerwartet. Fachbegriffe, die eingeführt wurden, sollten im Glossar stehen und im Text möglichst mit derselben Schreibweise auftauchen. Kontrollieren Sie auch Abkürzungen: Sind alle notwendigen Abkürzungen bei erstem Auftreten erklärt?
• Layout (Ausgabekontrolle): Führen Sie einen Probedurchlauf der Publikation durch (z. B. generieren Sie ein PDF oder HTML-Preview in FrameMaker/Oxygen). Überprüfen Sie das visuelle Erscheinungsbild: Stimmen Überschriftenabstände, Listeneinrückungen, Tabellenformatierungen? Gibt es unerwartete Umbrüche, z. B. einzelne Überschrift am Seitenende (typografische Waisen)? Im Online-Format: Funktionieren Navigationselemente, Klapptexte, Suchfunktion? Bilder und Screenshots: Sind sie scharf, lesbar, aktuell (zur Software passend) und mit korrekter Beschriftung/Nummerierung? Stellen Sie sicher, dass wichtige Elemente nicht abgeschnitten sind. Seitenzahlen, Verzeichnisse (bei PDF): Inhaltsverzeichnis vollständig und klickbar, Indexeinträge vorhanden und korrekt sortiert, Seitennummerierung durchgängig. Prüfen Sie auch auf platzhalterhaften Text (z. B. „Fehler: Unknown Link“) – solche Hinweise deuten auf ein Build-Problem hin. Idealerweise erstellt man für die Layoutprüfung ein finales Ausgabe-PDF und blättert es wie ein Leser durch.

Nachdem diese Punkte kontrolliert und etwaige Mängel behoben wurden, sollte das Dokument bereit zur Freigabe sein. Viele Teams nutzen Tools, um einige dieser Prüfungen zu automatisieren (z. B. Broken-Link-Checker, Spellchecker, Stylechecker), doch der menschliche Blick – besonders auf Inhalt und Verständlichkeit – bleibt unverzichtbar. Mit der obigen Checkliste kann kein wichtiger Aspekt übersehen werden.

8. Fazit

DITA hat sich als mächtiges Mittel erwiesen, um Softwaredokumentation in den Griff zu bekommen. Durch die konsequente Modularisierung in Topics, standardisierte Strukturen und hohe Wiederverwendung bietet DITA Softwareteams Skalierbarkeit und Effizienz: Große oder mehrere Dokumentationssätze lassen sich ohne Informationsverlust handhaben, Redundanzen werden minimiert, und konsistente Updates über viele Publikationen hinweg sind möglich. Gerade in Zeiten agiler Entwicklung verkürzt DITA den Abstand zwischen Code und Dokumentation – Änderungen können zeitnah, oft automatisiert, in alle betroffenen Handbücher, Hilfesysteme oder API-Dokumente übertragen werden. Übersetzungen profitieren enorm vom Single-Source-Prinzip: Wiederverwendete Segmente werden nur einmal lokalisiert, was nicht nur Kosten spart, sondern auch die Konsistenz zwischen Sprachversionen erhöht. Für Qualität und Compliance bedeutet DITA: klare Strukturen, weniger Fehler und lückenlose Nachvollziehbarkeit. Teams können präziser nachweisen, wann welcher Inhalt warum geändert wurde, was in regulierten Branchen und für interne Audits ein großer Pluspunkt ist.

Die Zusammenarbeit von DITA mit Adobe FrameMaker erweist sich dabei als leistungsfähige Kombination. FrameMaker bringt ein robustes Editor-Umfeld, in dem technische Redakteure effizient arbeiten können, ohne sich im XML-Code verlieren zu müssen. Seine Stärken – WYSIWYG-Editing, umfangreiche Template-Steuerung, integrierte Ausgabe – erleichtern den Umstieg auf DITA, insbesondere wenn bestehende Teams aus der Word/FrameMaker-Welt kommen. Wichtig ist, ein paar Erfolgsfaktoren im Auge zu behalten: Zum einen sollte das Team geschult sein, im strukturorientierten Paradigma zu denken – also weg von dokumentzentriertem Schreiben, hin zu modularer Content-Erstellung. Ein solider Informationsarchitektur-Plan und ein gepflegter Styleguide bilden das Fundament dafür. Zum anderen muss FrameMaker geschickt in den Prozess eingebunden werden: Als Editor top, aber für die Massenpublikation und Versionsverwaltung sollte es Hand in Hand mit Build-Skripten und ggf. einem CCMS arbeiten. Disziplin bei der Nutzung (keine wilden manuellen Formatierungen, konsistente Anwendung der Vorlagen) stellt sicher, dass die Vorteile von DITA voll zum Tragen kommen.

Als nächste Schritte für Organisationen, die den Einstieg suchen, empfehlen sich typischerweise folgende Maßnahmen: Initiales Assessment – holen Sie eine Bestandsaufnahme ein, ob und wo DITA den größten Nutzen bei Ihnen stiften kann. Identifizieren Sie „low hanging fruits“, etwa ein stark redundantes Handbuch, das man als Pilot migriert. Danach ein Pilotprojekt aufsetzen – in kleinem Rahmen DITA + FrameMaker ausprobieren, Prozesse definieren, eventuell erste Inhalte migrieren. Aus dem Pilot und den gewonnenen Erkenntnissen lässt sich eine fundierte Roadmap erstellen, um Schritt für Schritt DITA im gesamten Dokumentationsbereich auszurollen. Dies sollte unbedingt unter Einbeziehung aller Beteiligten geschehen: Produktmanagement (sieht den strategischen Wert), Entwicklung (liefert die technischen Inputs, die Verzahnung mit dem Dev-Prozess ist wichtig), Übersetzungspartner (stellen sich auf neue Formate ein) und natürlich die Redaktionsteams selbst (sie tragen das neue System am Ende). Mit einer solchen gesamtheitlichen Herangehensweise – unterstützt durch erfahrene Beratung und bewährte Tools wie FrameMaker – kann der Wechsel zu DITA reibungslos gelingen. Die Belohnung sind effiziente, zukunftsfähige Dokumentationsprozesse, die mit dem Tempo der Softwareentwicklung mithalten und qualitativ hochwertige Information für alle Stakeholder liefern. DITA in der Softwaredokumentation ist somit kein Selbstzweck, sondern ein Enabler: für bessere Information, glücklichere Nutzer und letztlich erfolgreichere Softwareprodukte.

 

Weitere Beiträge zum Thema DITA und Adobe FrameMaker