Blog

How to become a technical writer – Confessions of a former translator

A former translator, I worked the first seven years of my professional life in the translation industry, in various positions. While I learned a lot from this experience, it also left me, as a writer, frustrated. Translators are chained to their source text and writing the words of others in another language, usually focusing on what their clients want. mehr ...

tekom-Impressionen Teil 2: API-Dokumentation und die VUKA-Welt

Daniela Herbold und Ulrike Parson berichten über Leitlinien für eine optimierte API-Dokumentation sowie Lösungsansätze für eine innovative Personalführung. mehr ...

tekom-Impressionen Teil 1: Improvisationstechniken, Fluff Hunt und Videos

Auf dem Weg zur Konferenz sehe ich an der Fassade des Stuttgarter Bahnhofs ein Zitat von Hegel: „daß diese Furcht zu irren schon der Irrtum selbst ist“. Genau darum ging es in Anthonys Apodacas Vortrag am Morgen des zweiten Konferenztages. mehr ...

My first time at tekom

I got back from Stuttgart last night and it is safe to say that after three days of action-packed presentations, writing an article is not in the realm of possibilities right now as I try to connect one synapse with another. mehr ...

Eine Tasse auf Reisen #4 - die Auflösung

In welcher Stadt wurde die parson-Tasse fotografiert, haben wir Anfang September gefragt. Die Frage war knifflig. Trotzdem kamen die meisten auf die richtige Antwort: In Chicago, USA. mehr ...

Von Word nach DITA. Fragen, Antworten und ein paar Fakten

Neulich fragte eine Kollegin auf XING, ob und wie sie auf eine DITA-basierte Autorenumgebung umsteigen könne. Mark Schubert und Ulrike Parson von parson communication haben ihre Fragen beantwortet.

 

Die Kollegin beschrieb ihr aktuelles System wie folgt:

  • Benutzerhandbücher, in Word erstellt und linear aufgebaut. Sie werden in der Regel von vorne nach hinten gelesen.
  • Referenzhandbücher, in Word erstellt. Hier handelt es sich um Sammlungen von Einzeltexten, die nach verschiedenen Kriterien sortiert sind, z. B. Beschreibungen von Programmbefehlen.
  • Online-Hilfe, gespeist aus den Benutzerhandbüchern, manuell gekürzt und befreit von Querverweisen und Formatvorlagen.

Da die dokumentierte Software ein modulares Konzept habe, wolle sie projektbezogene und kundenspezifische Dokumentation erstellen. Außerdem wollte sie wissen, ob sie bei dem Umstieg auch die vielen hundert Textseiten hinüber retten könne.

DITA (Darwin Information Typing Architecture) ist ein Dokumentenformat auf der Basis von XML für die Konzeption, Erstellung, Verwaltung und Veröffentlichung von Informationen. DITA ermöglicht die Wiederverwendung themenorientierter Inhalte als Bausteine (Topics) und ist geeignet für die Organisation umfangreicher Dokumentation.

parson communication:
Die gute Nachricht zuerst: Die technische Umsetzung ist in der Regel kein Problem.

Kollegin:
Und die schlechte?

parson communication:
Der möglicherweise hohe Aufwand bei der Aufbereitung der alten Inhalte. Grundlage von DITA ist die Aufteilung eines Inhalts in Bausteine, die sogenannten Topics.

Sind in den Ausgangsdaten die Informationstypen, z. B. die Referenzinformationen, nicht sauber von Konzepten und Anleitungen getrennt, erhöht sich der Aufwand bei der Aufbereitung der alten Inhalte. Dann müssen Inhalte umgeschrieben werden, um in die semantische DITA-Struktur zu passen. Auch wenn es bei Ihnen bereits unterschiedliche Handbücher gibt, entspricht die Struktur der Texte vermutlich noch nicht DITA. Sind die alten Inhalte bereits klar strukturiert, ist der Aufwand geringer.

Topics sind Informationsblöcke, die ein bestimmtes Thema behandeln. Sie sind in sich geschlossen und unabhängig von anderen Topics. Auf diese Weise kann man Topics an verschiedenen Stellen in der Dokumentation, in denen das Thema vorkommt, verwenden. Topics werden klein gehalten, um sie flexibel verwenden zu können. Topics werden in unterschiedliche Informationstypen unterteilt. Die wesentlichen sind: (1) Task: erläutern, wie der Benutzer eine Aufgabe löst. (2) Concept: beschreiben grundlegende Zusammenhänge oder Architekturen. (3) Reference: listen Fakten, Parameter, technische Daten usw auf. Werden häufig in Tabellen oder Listen abgebildet.

Kollegin:
Wie soll ich nun am besten vorgehen?

parson communication:

  1. Machen Sie eine Bestandsanalyse. Überprüfen Sie Ihre bestehenden Texte auf Gemeinsamkeiten und Unterschiede, und zwar sowohl auf Ebene des Informationsproduktes (des Buches) als auch auf der Kapitelebene. Listen Sie sämtliche Varianten der Dokumentation auf (z. B. für verschiedene Zielgruppen, Produkte und Ausgabeformate).
  2. Definieren Sie Ihre Anforderungen. Da es mit Sicherheit Unterschiede zwischen den einzelnen Informationsprodukten und ihren Varianten gibt, wäre Ihr Ziel so etwas wie der gemeinsame Nenner der Dokumente.
  3. Bilden Sie den Zielzustand in DITA ab. Meistens bietet DITA mehr als Sie benötigen. Viele verwenden daher nur eine Untermenge der angebotenen DITA-Elemente und passen einige weitere an ihre Anforderungen an. Teilen Sie versuchsweise Ihre alten Kapitel auf und bauen Sie sie in die DITA-Topics ein.

Kollegin:
Wie groß oder klein sollten denn meine Topics sein? Was ist, wenn ich später feststelle, dass mein gewähltes Raster zu groß war und ich ein Topic weiter zerlegen muss. Ist das nicht aufwändig? Oder sollte ich von Anfang an eher zu kleine als zu große Topics generieren?

parson communication:
Grundsätzlich würde ich kleine Einheiten wählen, z. B. wird eine konzeptionelle Info ein Concept-Topic. Wenn mehrere Topics gruppiert werden sollen, kann das über eine DITA-Map geschehen. Ein großes Topic aufzuteilen und eine DITA-Map daraus zu machen, geht relativ schnell. Wenn es sehr viele sind, kostet das aber auch Zeit.

In DITA-Maps sammeln und organisieren Sie Ihre Topics für die Online- oder die PDF-Ausgabe. Basierend auf DITA-Maps können Sie Inhaltsverzeichnisse erstellen und Links erzeugen, die den Topics hinzugefügt werden.*

Kollegin:
Aber was ist mit den Bildern? Muss ich die separat auslagern?

parson communication:
Bilder werden in einem Verzeichnis separat abgelegt und über ein DITA-Element referenziert. Die Bilder werden dann an der Stelle im Topic angezeigt.

Kollegin:
Die aktuelle Softwaredokumentation enthält eine große Anzahl von Screenshots für die Druck- oder PDF-Ausgabe. In der kontextbezogenen Bildschirmhilfe sollen diese Screenshots nicht auftauchen, da der Kunde ja ohnehin das Fenster offen hat, wenn er die Hilfe aufruft. Muss ich im Text darauf verzichten, auf das Bild zu verweisen, oder kann ich Halbsätze wie "siehe Abbildung 13" beim Export in manche Formate (z. B. PDF) mitnehmen und für andere Formate (z. B. HTML) weglassen?

parson communication:
Sie können innerhalb eines Topics Varianteninformationen zuweisen, d. h. in einem XML-Attribut angeben, dass die Grafik nur für den Druck bestimmt ist. Mit diesen sogenannten attributbasierten Bedingungen können Sie auch andere Textteile ein- oder ausblenden, z. B. auch Halbsätze. In diesem Fall legt man ein <phrase>-Element um den Textteil. Dieses <phrase>-Element bekommt dann ein entsprechendes Attribut.

Kollegin:
Also ich habe mal gelernt, dass ein Bild, auf das im Text kein Bezug genommen wird, überflüssig ist.

parson communication:
Beim Single-Source-Publishing muss man zwischen dem Arbeitsaufwand für den Redakteur und der Lesbarkeit für den Anwender abwägen. Wir verwenden auch gerne Screenshots, z. B. in Handlungsanweisungen. Diese haben dann aber keinen Titel und es gibt keine Verweise auf sie. Im Kontext ist das gut lesbar und der Wartungsaufwand ist viel geringer. Wir machen auch einen Unterschied zwischen Screenshots und Abbildungen. Letztere sind auch in der Online-Hilfe nützlich und auf die verweisen wir dann auch.

Kollegin:
Brauche ich ein Redaktionssystem für den Umstieg auf DITA?

parson communication:
Nein. Man braucht nicht zwangsläufig ein Redaktionssystem, um DITA zu verwenden. Sie können z. B. mit einem XML-Editor wie Oxygen arbeiten und die Module mithilfe von Maps verwalten. Die XML-Dateien und Maps können Sie z. B. in einem Source-Code-Managementsystem wie Perforce oder Subversion verwalten. Aber: Ab einer gewissen Menge an Topics und einer gewissen Zahl an Varianten werden ausgefeiltere Strategien zur Verwaltung der Inhalte nötig. Und die bieten XML-basierte Redaktionssysteme.

Leseempfehlung

  • Laura Bellamy: DITA Best Practices: A Roadmap for Writing, Editing, and Architecting in DITA, Addison-Wesley Longman, Amsterdam, 2011.
  • Sissi Closs: Single Source Publishing. Topicorientierte Strukturierung und DITA, Entwickler-Press, 2007.

* (übersetzt aus: http://dita.xml.org/faq-map-architecture-dita)

Kommentar schreiben


  • facebook
  • linkedin
  • xing