Redakteuse live – tekom Jahrestagung 2010

Die alljährliche tekom-Jahrestagung rückt näher und ich freu mich schon riesig.

Noch mehr freue ich mich, wenn ich den einen oder anderen Leser für meinen Vortrag „User assistance mit DITA“ gewinnen kann – gerne auch die Kollegen mitbringen 😉

Hier nochmal als Erinnerung, wann und wo ihr mich dort finden könnt:

User assistance mit DITA – Do 04.11., 11:15 Uhr, Raum 6.2

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 🙂

Arbeite mit DITA und sprich darüber?

Ich war in den letzten Monaten häufiger in der Situation, das ich Kollegen aus anderen nicht-TR-Abteilungen erklären musste, wie wir in unserem Team eigentlich inzwischen Hilfe schreiben und warum manches nicht mehr so läuft wie früher.

Das Wort DITA nehme ich dabei übrigens eigentlich nur ganz nebenbei in den Mund. Warum? Weil es den Damen und Herren total egal sein kann 🙂 Das ist jetzt nicht überheblich gemeint, aber es ist für sie ja auch gar nicht wichtig zu wissen,dass wir mit DITA arbeiten. Viele Leute konzentrieren sich oft viel zu sehr darauf einem zu erklären WIE sie etwas machen anstatt dass sie einem erklären WAS es den Beteiligten bringt. Oft beobachtet bei Entwicklern, die einem gern die Namen der neuesten Trendtechnologien um die Ohren hauen, die einen dann nur ratlos schauen lassen…

In unserem Fall ist das Prinzip unserer neuen Arbeitsweise an und für sich beispielsweise das wirklich Essentielle:

  1. Standardisierung
  2. Topic-Orientierung
  3. Trennung von Inhalt und Layout

Das sind die wichtigsten nach außen sichtbaren Vorteile und ich konzentriere mich lieber darauf diese transparent zu machen als dass ich groß DITA erkläre.

Man muss hierbei bedenken, dass sich das Vehikel mit dem wir diese Prinzipien umsetzen, auch mal ändern kann.

Die Abteilungen mit denen ich hier zusammen arbeite sind in der Regel vom Endergebnis betroffen und dann kann ihnen das WIE völlig egal sein. Sie müssen vor allem wissen warum sie die neue Arbeitsweise gut finden sollen 😉

User assistance mit DITA – Redakteuse live

Es war etwas ruhig in den letzten Monaten. Das lag nicht zuletzt an einem äußerst spannenden Projekt mit DITA, das zwar genug Bloggenswertes ergab, aber auch dafür sorgte, dass ich gar nicht dazu kam zu bloggen bzw. auch mal nicht über DITA nachdenken wollte 🙂

Nichtsdestotrotz will ich meine Erfahrungen zum Thema „User assistance mit DITA“ gerne weitergeben und praktischerweise ist mein Vortragsvorschlag dazu für die tekom-Jahrestagung 2010 angenommen worden 🙂

Einen Vorgeschmack auf den Inhalt gebe ich euch schon hier und freue mich natürlich über jeden Zuhörer 🙂

Die Herausforderung: eine kontext- und tarifabhängige Software-Hilfe, die den Kunden in seinen ersten Schritten begleitet. Dieser Vortrag stellt den Projektverlauf vor, in dem diese „embedded help“ entwickelt wurde. Der Bogen wird dabei von den wirtschaftlichen Beweggründen über die technische Umsetzung mit DITA bis hin zu den Lessons learned gespannt. Einen Schwerpunkt bilden dabei die Möglichkeiten, die man mit DITA out-of-the-box hat, und jene, die man erst selbst entwickeln muss.

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 🙁