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

Breadcrumbs in DITA-XHTML – Update

Ich habe das Breadcrumbs-Plugin ja bereits vorgestellt. Der damalige Bug bei der Verwendung von Reltables war sehr schnell behoben – superklasse!

Aber schon damals ist mir eine unschöne Sache aufgefallen: der Text für das Wurzelelement in der Breadcrumb ist hart kodiert. Das ist natürlich gerade bei der Internationalisierung der Hilfe eher so ein bisschen doof. Schließlich will ich ja nicht für jedes Generieren jeder Sprache immer wieder die Stylesheets anfassen. Daher hab ich eine Internationalisierung an dieser Stelle eingebaut, d.h. der Text für das Wurzelelement wird je nach Sprache der Map & Topics generiert.

Wer sich dafür interessiert, befolge bitte diese Schritte:
In der Datei dita.xsl.maplink.xsl aus dem Plugin wird dieser Schnipsel
<xsl:param name="indexLinkText" select="'Index'"/>>

zu diesem


<xsl:param name="indexLinkText">
<xsl:call-template name="getString">
<xsl:with-param name="stringName" select="'Start'"/>
</xsl:call-template>
</xsl:param>

In der de-de.xml im xsl-Verzeichnis des Toolkits muss natürlich der entsprechende String angelegt werden:
<str name="Start">Start

Dann muss man noch den obigen Schnipsel aus Zeile 9 in das xsl-Template (ab Zeile 14) verschieben, also so:

<xsl:template match="*" mode="link-to-other">
<xsl:param name="pathBackToMapDirectory"/>
<xsl:param name="indexLinkText">
<xsl:call-template name="getString">
<xsl:with-param name="stringName" select="'Start'"/>
</xsl:call-template>
</xsl:param>
<xsl:if test="$doAncestors='yes'"> ......

Wenn man die Parameterdefinition global belässt, wird immer nur en-us als Sprache erkannt, warum auch immer.

So, das war's auch schon. Und zu meinen Tricks, um mich beim Programmieren und Testen bei Laune zu halten, gehören motivierende Ausgabetexte für den Fall, dass es endlich klappt, und eher so die destruktiven für den anderen Fall ;-)

Geschrieben in Allgemein | Keine Kommentare

tekom-Jahrestagung 2009 #2 – Dating DITA

Ich war in sage und schreiben einem DITA-Vortrag. Erstens gab es davon gar nicht so viele (“Der Hype flaut ab”, wie ein CMS-Hersteller mir bestätigte), zweitens waren die meisten davon eher auf einem Anfängerlevel.

Bei diesem Vortrag war ich fast geneigt nicht hinzugehen, da mir der Titel zuerst zu gewollt witzig vorkam. Ein Blick in den Tagungsband hat mich dann doch überzeugt.

Hier ging es um einen rein semantischen Blick auf DITA – was ich zur Abwechslung mal sehr erfrischend fand. Das ganze hier spielte hier keine Rolle:  “Dann kannst du auch noch das machen – und Maps und Conref… und DITAVAL… das Open Toolkit und Spezialisierung”

DITA – die Informationsarchitektur

Im Blickpunkt stand: die Sicht des Redakteurs. Kann man als Redakteur relativ einfach mit der DITA-DTD arbeiten? Erschließen sich bspw. Elementnamen sofort (“Self-documenting structure”), braucht man am Ende keinen Styleguide mehr?

Ralf Steiner und sein Team haben sich DITA angeschaut und ihnen ist Folgendes aufgefallen

  • endlos viele Titles (searchtitle, navtitle, title) und keine gute Abgrenzung
  • Abgrenzung zwischen abstract und shortdesc unklar
  • das Schachteln von versch. Topictypen ist fragwürdig.
    Ich finde es schon fragwürdig, zwei tasks ineinander zu schachteln.
  • Unterschied zwischen choices und choicetable ist unklar.
    Für mich ist das eine Layoutsache, manchmal lassen sich Handlungsvarianten besser tabellarisch darstellen. Aber natürlich ist das wieder so eine Sache, weil man ja hier semantisch denken sollte und nicht layoutorientiert. Doch zu 100% lässt sich das nie trennen, wie ich festgestellt habe.
  • Was soll das info-Element, wo doch ein Task keine Hintergrundinfo geben soll?
    Nun ja, ganz ohne Hintergrundinfo geht es eben nicht. Ich platziere hier auch nur Hintergrundinfo, die sich auf den spezifischen Schritt bezieht, daher hab ich an dem Element nichts auszusetzen.
  • Wozu braucht man steps-unordered?
    Ja, allerdings, wozu? Ob die Steps später nummeriert werden oder als Bullets dargestelt werden, entscheidet sich doch erst beim Generieren.
  • Die Concept-Topics sind eine Glaskugel aus der man alles ableiten kann.
    Oh ja! Ich habe bis heute nur eine vage Idee, wie ich Concepts wirklich standardisieren soll.
  • Die Benennung der Element ist inkonsistent bzw. nicht sprechend. Man könnte eine dl auch deflist nennen, äquvalent zur linklist.

Ich füge noch hinzu:

  • Abgrenzung zwischen context und shortdesc ist schwammig.
  • Wozu werden related-links ermöglicht, wenn man doch nur die Wiederverwendung damit erschwert und Relationship tables eigentlich viel besser sind?
  • Für Tasten gibt es kein Element! Wie soll den Software-Dokumentation ohne Tasten gehen? Ich habe uicontrol daher eben auch hierfür als Auszeichnungselement definiert.
  • Ich kann das p überall benutzen, aber sollte ich auch? Zum Beispiel innerhalb von note, li, shortdesc, context etc.

DITA – ohne Styleguide? Lieber nicht…

Das ist das Fazit von Ralf. Und da kann ich mich voll und ganz anschließen. Ich habe auch zuerst ein Funktionsdesign erarbeitet und dann quasi mit DITA verheiratet. Es sind einfach zu viele Elemente, die nicht eindeutig out-of-the-box zu befüllen sind. Und man hat ja auch bei der Strukturierung immer noch sehr viele Freiheiten, die am Ende dann auch nicht mehr wirklich Standardisierung bedeuten.

Insgesamt ein sehr guter und gut gehaltener Vortrag, der sich mal dem gewidmet hat, auf das es am Ende ankommt: kann man gut damit arbeiten?

PS: Zu viele Bilder der personifizierten DITA sind dann irgendwann auch nicht mehr witzig…

Geschrieben in DITA,Erweiterter Horizont,Redakteurs Alltag,Softwaredokumentation,Usability | 2 Kommentare

tekom-Jahrestagung 2009 #2 – Embedded help

So, ich versuche mal einige Vorträge derselben Themengebiete zusammenzufassen:

Nicoletta Bleiel, ComponentOne – Improving Software Usability with Embedded User Assistance

Ich hatte Nickys Vortrag aus dem letzten Jahr noch gut im Gedächtnis und da auch das Thema passte, bin ich also nichts wie hin.

Hauptthema war Hilfe, die in die Software eingebettet ist und sich nicht außerhalb des Nutzungskontexts befindet. Damit soll gewährlkeistet werden, dass man den Nutzer nicht aus seinem Workflow reißt, indem man ihn dazu zwingt erst einmal die Hilfe zu öffnen, zu suchen, die “richtige” Frage zu stellen etc. Embedded help wird oftmals gar nicht als “Hilfe” empfunden.

Nicky zeigte uns hier ihre Umsetzung davon bei der Hilfe von Doc-to-help.

Das Besondere hier war ein bestimmtes Modul, das es dem Redakteur ermöglicht sehr einfach einen Bezug zwischen einem GUI-Element und einem Hilfetext herzustellen – direkt am Interface und nicht über die Verwaltung von irgendwelchen GUI-Element-IDs. Sprich: der Redakteur markiert ein GUI-Element (Button / Menüpunkt etc) , öffnet einen bestimmten Hilfetext in der Applikation und stellt so einen Bezug zwischen den beiden her. Wenn also der Nutzer das entsprechende GUI-Element anklickt o.ä., kommt direkt der dazu passende Hilfetext.

Leider ist das Modul nur in .NET-Applikationen verfügbar. Ich finde diese visuelle Unterstützung für das Mapping äußerst attraktiv (nicht zuletzt, weil ich mich bald mit diesem Thema beschäftigen werde und da wohl eher die Lösung mit GUI-IDs übrig bleiben wird).

Im restlichen Teil des Vortrags hat Nicky ihre Vorgehensweise dargestellt – von der Konzeption bis zur Umsetzung verriet sie Tipps und Tricks, u.a.:

  • keine Sackgassen-Topics, d.h. jedes Topics sollte verwandte Topics verlinken, und wenn es nur die Verlinkung von Eltern-Kind-beziehungen ist.
  • Trotz kontextbasierter Hilfe bei der Erklärung von Funktionen immer auch erwähnen, wie man eine Funktion findet. Ein Nutzer liest den Hilfetext evtl. nicht im Kontext und weiß gar nicht, wie er die Funktion erreichen kann.

Weitere Details könnt ihr auch inNickys entsprechendem Artikel auf der tcworld nachlesen.

User Assistance 2.0 – Produktinformation als Mittel für Kundenbindung und Kundenmehrwert

Anfangs wurde hier die These aufgestellt, dass Serviceangebote, eben auch umfassende Hilfeangebote, zukünftig immer wichtiger werden. Irgendwann hat jede Produkt-Featuritis ein Ende: man kann einfach nichts mehr Sinnvolles dazubauen. Und dann fängt man eben mit Dienstleistungen an.

Hier hat t3 eine ganzheitliche Informationslösung zusammengestellt, die ich persönlich ziemlich cool fand. Angefangen von embedded help, die sich konkret auf aktuelle Aufgaben bezieht, hin zu einer  dynamischen Hilfe, die mehr prozessorientiert und wissensvertiefend angelegt ist. Am Ende steht ein Wissensportal, das sowohl prozess- und aufgabenorientiert augebaut ist als auch produkt- und themenorientiert. Durch das Portal hat man auch einen Feedbackkanal und gibt den Nutzern auch die Möglichkeit eigene Tipps & Tricks und sogar Dateien austauschen können.

Diese “mehrstufige Vernetzung” hat mir sehr gut gefallen. Jeder Mensch verhält sich ein bisschen anders bei der Informationssuche und dieses Konzept deckt für mich ein großes Spektrum ab.

Software und Dokumentation – Mit XML zusammenfügen, was zusammengehört

Hier wurde eine sehr spezifische Lösung präsentiert, wie ein Hilfetext in die Software-Oberfläche gelangen kann. Die hier eingebettete Hilfe war jedoch relativ statisch ohne Navigations- oder Suchmöglichkeiten und auch optisch eher “nüchtern” – das ist sicher noch ausbaufähig. Es wurde vor allem auf den Prozess eingegangen, d.h. wie der Austausch zwischen Redaktionssystem und Software funktioniert.  Ich glaube mich noch zu erinnern, dass ich das ganze etwas frickelig fand – spätestens bei der Excel-Tabelle, die für bestimmte Workarounds nötig ist, war ich etwas entsetzt (aber wer hat sie nicht, die kleinen ekligen Workaorunds, die man lieber nicht weitererzählt….).

Das Endergebnis ist ein rudimentäres Beispiel von embedded help und höchstens dahingehen interessant, wie das Zusammenspiel zwischen Doku und Entwicklung funktionieren kann.

Geschrieben in Allgemein | Keine Kommentare

tekom-Dokupreis 2009 im Visier

Der diesjährige Dokupreis ging an einen Waffenhersteller.

Das ganze hat ein wenig Wirbel ausgelöst – einerseits bei Friedensaktivisten, andererseits wurde die Frage aufgeworfen, ob hier alles korrekt abgelaufen ist.

Zu letzterem: ich kann es mir nicht wirklich vorstellen, dass hier quasi Bestechung stattgefunden haben soll, aber das ist auch schon alles, was ich dazu sagen kann. Mir kommt es so vor, als ob der Hersteller sich einfach noch einmal rückversichern wollte, dass die Anleitung auch wirklich toll ist, bevor sie eingereicht wird. Und das wäre echt etwas affig…

Mich stört eher der Aspekt, dass eine Waffenanleitung gewonnen hat. Mein erster Gedanke bei der Nachricht, war einfach: “Spinnen die total?”. Auch Prof. Schwermer – ehemals Jurymitglied- hat diese Anleitung wohl verstimmt:

Im März 2009 verlässt Schwermer die Jury, weil er es verwerflich findet, an der Prämierung von Waffenanleitungen mitzuwirken. (Quelle)

Ich habe TR-Fremde aus meinem privaten Umfeld dazu befragt und habe u.a. gehört: “Na, bei Waffen ist doch eine gute Anleitung gerade wichtig.” / “Das ist auch Teil der Wirtschaft.”

Nach meiner ersten Reaktion hab ich mir auch einige Fragen gestellt:

  • Darf man so eine Firma von vorneherein aus so einem Wettbewerb ausschließen?
  • Fängt da nicht schon eine Art ungerechte Selektion statt?
  • Muss nicht einfach das TR-Handwerk bewertet werden, unabhängig ob es eine Saftpresse oder eine Waffe ist?
  • Und wenn wir mit der Moral als Instanz beginnen – wer definiert die Grenzen dazu?

Der Versuch diese Fragen zu beantworten, erklärt mir schon warum diese Anleitung nicht “rausgeworfen” wurde. Objektiv und fair betrachtet spricht nichts dagegen diese Industrie in so einem Wettbewerb zuzulassen. Alleine: mir bleibt trotzdem ein schaler Nachgeschmack, wenn ich daran denke.

Ich jedenfalls könnte es nicht mit mir vereinbaren hier an einer Bewertung mitzuwirken. Und eigentlich wünsche ich mir – so ganz persönlich-, dass das auch anderen so ginge.

Geschrieben in Beruf,Erweiterter Horizont | Keine Kommentare