Mit DITA um die Welt – tekom-Jahrestagung 2012

Die tekom-Jahrestagung 2012 ist überstanden und es war mal wieder sehr interessant und schön dabei zu sein.

Vorab gibt es hier erst einmal die Folien zu meinem Vortrag “Mit DITA um die Welt”. Der Rückblick folgt in den nächsten Tagen. Ich gehöre nicht zu den Schnell-Bloggern wie Kai oder Sarah, die ihre Eindrücke wirklich rasend schnell online hatten.

Und hier noch der Beweis, dass ich ihn tatsächlich gehalten habe ;-)
(Special thanks to Axel)

Vortragsbild "Mit DITA um die Welt"

Geschrieben in DITA,Lokalisierung | 1 Kommentar

Linkklassen und Usability

Das DITA-Open Toolkit unterscheidet im XHTML-Output zwischen Links auf Concepts, References und Tasks. Konkret werden die Links wie hier angezeigt:

Mal abgesehen davon, dass die vom Open Toolkit mitgelieferten deutschen Standard-Überschriften “Zugehörige Konzepte/Tasks” etwas wunderlich klingen, bin ich persönlich kein Freund dieser Aufteilung der Links.

Ich habe z.B. an der Hochschule gelernt, dass solche Topic-Beziehungen klassifiziert und standardisiert werden sollten. Zum Beispiel indem man festlegt, welche Topictypen einander verlinken dürfen und wie. Das finde ich auch absolut okay und notwendig, denn so kann man verhindern, dass unsinnige Link-Urwälder entstehen in denen jedes Topic jedes andere Topic verlinkt, was dann am Ende nicht mehr sehr hilfreich für den Nutzer ist.

Aber: ich bin mir nicht sicher, ob diese Klassifizierung dem Nutzer an dieser Stelle unbedingt so vermittelt werden muss. Hat der Nutzer tatsächlich etwas davon, wenn ich ihm sage: hier kannst du verwandte Anleitungen finden und hier verwandte Erklärungen? Manchmal weiß der Nutzer doch selbst gar nicht so genau was er sucht und ist so eine Klassifizierung nicht vielleicht einfach nur ein Stolperstein?

In meinen Augen ringt so eine Aufteilung dem Nutzer noch einmal eine Entscheidung zuviel ab, die er auf der Suche nach der passenden Information treffen muss.  Er muss sich dann nochmal fragen: “Ja, was such ich denn eigentlich?” und ehrlich gesagt ist man nicht in der Stimmung über so etwas nachzudenken, wenn man Hilfe sucht. Daher plädiere ich dafür verwandte Links unter einer Überschrift zusammenzufassen. Mir geht diese Aufteilung auf Nutzerseite einen Schritt zu weit und sie hat so ein bisschen was von “Ich mach es so. Weil ich es kann.”

Wie seht ihr das? Was macht ihr mit Links auf verwandte Themen und warum?

Geschrieben in DITA,Erweiterter Horizont | 4 Kommentare

DITA-OT um Sprachen erweitern

Das DITA-Open-Toolkit bringt schon ziemlich viele Sprachen mit sich, aber irgendwo findet sich doch immer eine, die doch noch nicht abgedeckt ist.  Das Hinzufügen neuer Sprachen ist glücklicherweise kein Hexenwerk. Allerdings gilt letztere Aussage nur für Sprachen mit der Schreibrichtung “links nach rechts” – die andere Richtung hab ich noch nie getestet und weiß nicht, ob es da noch andere Dinge zu beachten gilt.

Das Sprachkürzel herausfinden

Im Attribut xml:lang jedes Topics muss die Sprache angegeben werden. Es gibt verschiedene Übersichten im Netz über diese so genannten “Locale IDs” , z.B. hier. Nehmen wir mal an, ich möchte kolumbianisches Spanisch einbinden. So lautet das Kürzel also: es-co.

Sprache in strings.xml hinterlegen

  1. Öffne das Verzeichnis xsl/common in deinem DITA-OT.
  2. Öffne die Datei strings.xml.
  3. Kopiere die Zeile mit der Definition des Spanischen und füge die Kopie direkt drunter ein.
  4. Ändere das Sprachenkürzel entsprechend der gewünschten Sprache, hier als Beispiel kolumbianisches Spanisch.
    es-co

Neue Sprachdatei anlegen

  1. Kopiere eine der vorhandenen Sprachdateien aus dem Verzeichnis xsl/commonund füge sie unter dem Namen es-co.xml in dasselbe Verzeichnis ein.
  2. Übersetze die Strings in der Datei in die gewünschte Sprache. Oder lasse übersetzen ;)
  3. Kopiere die Zeile mit der Definition des Spanischen und füge die Kopie direkt drunter ein.

Fertig!
Das war es tatsächlich schon. Ab sofort kannst du in den Topics und Maps das neue Sprachkürzel verwenden und die automatischen Strings wie z.B. “Hinweis” oder “Achtung” werden entsprechend lokalisiert :)

Geschrieben in DITA,Lokalisierung,Übersetzung | 4 Kommentare

Metadaten-Chaos: Komplette Topics filtern

Der Dating DITA-Vortrag kommt mir gerade wieder in den Sinn, wo ich mich Metadaten beschäftige. Und da stehen mir wirklich die Haare zu Berge – das ist das erste Mal, dass ich DITA wirklich, wirklich unpraktisch finde und noch keine gute Lösung habe, wie ich da in Zukunft verfahren soll.
Wie man komplette Topics nicht rausfiltert
Nehmen wir mal an, ich generiere aus einer Map einen User-Guide und einen Admin-Guide. Viele Inhalte überschneiden sich, aber einige sind exklusiv nur für eine der Zielgruppen gedacht.

Bisher dachte ich mir das so: Wenn ich von einem kompletten Topic weiß, dass es nur audience=”user” ist, dann setz ich das Attribut auf das Root-Element, also so:
<task id="123" product="wundertuete2" audience="user">...

Dann wird doch dieses Topic, auf diese Weise attributiert, nun beim Generieren des Admin-Guides bestimmt nirgends verlinkt bzw. gar nicht erst generiert.

Weit gefehlt. Das Topic wird generiert und zwar leer (und damit nicht valide). Alle Verlinkungen, sprich: alle Topicrefs, sind auch im Output existent, führen aber natürlich ins Leere.

Wie man komplette Topics wirklich rausfiltert
Um zu verhindern, dass etwas überall verlinkt wird, muss man das Attribut auf jeden Topicref setzen!
<topicref id="123" product="wundertuete2" >
<</topicmeta></topicref>

Und zwar auf wirklich jeden, auch die in den Relationship tables. Und das in allen Maps in denen das Topics vorkommt. Wenn ich da an zentrale, so gut wie immer gültige Attribute wie audience oder product denke, wird mir übel. Wie soll man das denn anständig pflegen oder gar mal aktualisieren? So müsste jeder Redakteur für jedes Topic erneut prüfen, welche Gültigkeit es hat und es auch wieder in der Map hinterlegen. Und darauf hab ich eigentlich überhaupt keine Lust.

(Im Übrigen gilt das Prinzip nicht nur für Topicrefs, sondern auch für den Einsatz anderer interner Verlinkungsarten wie xref oder related-links)

Zudem ist es sehr inkonsistent, dass es hier plötzlich ein eigenes Element audience gibt, zusätzlich zum gleichnamigen Attribut. Um die Verwirrung zu komplettieren, kann man beides gleichzeitig auf einen einzelnen Topicref beziehen.

<topicref id="123" product="wundertuete2" audience="user">
<topicmeta></topicmeta></topicref>

Eine passende Diskussion auf der Yahoo-Group hab ich schon gefunden, aber eben leider noch keine Lösung. Und sowas muss ich kurz vor dem Wochenende rausfinden :(

Geschrieben in DITA,Usability | 1 Kommentar

Dateiendungen in DITA – kleines Problem

Heute ein kleiner Wissensschnipsel zu Dateiendungen in DITA. Prinzipiell ist es inzwischen erlaubt, sowohl Dateien mit XML-Endung als auch welche mit DITA-Endung in eine Map zu integrieren. Ich persönlich finde ja so einen Misch-masch nicht gut, und als ich es mal getestet habe, hat es auch nicht gut funktioniert.

Kommen wir aber zu einem Problem, das seine Ursache in diesem Misch-Masch hat, und das in den meisten Fällen gar kein Problem ist, außer man schafft es mal wieder einen Sonderfall zu erwischen. So wie ich ;-)

Ich musste gerade bei einer Transformation einem Topic die Information mitgeben, welchen Parent es hat – und zwar musste es die ID des Parents sein.

Da kam mir sehr gelegen, dass in unserem Redaktionssystem der Dateiname auch als Topic-ID fungiert .

<task id="d262.dita">...</task>

Also geb ich hier einfach das href-Attribut des Parents aus, das ja den Dateinamen beinhaltet. Sehr einfach, juhu!

<xsl:value-of select="../@href"/>

Aber Moment im Endergebnis der Transformation finde ich plötzlich das hier

   
     <topic  id="t_Duda.dita">
     <title>Duda</title>
      <topic parentid="t_Duda.xml" id="t_Dida.dita">

Die Parent-ID stimmt im Prinzip, bloß ist da plötzlich XML als Dateiendung angegeben! Was soll das denn jetzt?

Ich habe eine Weile gesucht, blieb aber ratlos. Ein Artikel zur Verwendungvon Dateien mit XML-oder DITA-Endung hat mich dann auf die Lösung gebracht. Beim Generieren der temporären Dateien aus denen das Toolkit letzten Endes die Ausgabe baut, kann man sich auch “aussuchen” welche Dateiendung diese temporären Dateien haben sollen.

Standardmäßig werden sie in XML generiert, aber das kann man in seinen Build-Dateien auch ändern.. Also habe ich in meine Build-Datei flugs folgenden Parameter eingebaut:

<param name="dita.extname" value="dita"/>

Und schon hat es gepasst!

     <topic " id="t_Duda.dita">
      <title>Duda</title>
      <topic parentid="t_Duda.dita"  id="t_Dida.dita">
Geschrieben in DITA | Keine Kommentare