Content-Management über Ordner und SubVersion

Wie man meinem Blog entnehmen kann, beschäftige ich mich seit ca. 2 Jahren mit DITA. Anfangs haben wir unsere Daten über Ordner und SVN verwaltet. Inzwischen haben wir schon fast alles im Redaktionssystem drin – das SVN ist bald Geschichte. Da ich aber weiß, dass ein Redaktionssystem häufig zu den unerfüllten Träumen von technischen Redakteuren gehört, teile ich hier mal meine Erfahrungen mit DITA und SVN.

Übersetzungsmanagement

Die einzelnen Sprachen auf demselben Stand zu halten gestaltet sich schwierig. Man muss sehr diszipliniert sein, denn sonst vergisst man leicht, dass ein kleiner Fix in der einen Sprache auf die anderen übertragen werden sollte.

Bei Änderungen an bestehenden Daten hat man das Problem, das man das Delta entweder manuell rauskopieren, übersetzen und dann wieder reinkopieren muss. Oder man gibt eben immer nur komplette Topics zur Übersetzung, auch wenn nur ein Satz neu ist (was aber schnell recht teuer werden kann).

Verwaltung

Versionshistorie ist Gold wert 🙂

Dateileichen herauszufinden ist schwierig, z.B. wenn man in der Konzeptionsphase mehrere Topics angelegt hat und am Ende einige gar nicht braucht. Bei uns sind solche Leichen teilweise übersetzt worden, obwohl sie nie gebraucht wurden. Hier können kleine Skripte hilfreich sein, die alle Dateien listen, die in keiner Map referenziert sind.

Man schludert schnell mit SVN-Kommentaren und am Ende weiß man selber nicht mehr, was man eigentlich mit  dem Kommentar „Änderung“ gemeint hat 😉

Tags und Branches sind äußerst wichtig, damit man komfortabel an neuen Projekten arbeiten kann und immer noch gleichzeitig den aktuellen Online-Stand aktualisieren kann. Am Anfang hab ich nur auf dem trunk gearbeitet, was darin resultierte, dass ich im Projektverlauf keine Updates am Online-Stand machen konnte und als sich dann das Projekt verschob, alle Änderungen händisch zurücknehmen musste.

Wenn man die Ordner erst einmal angelegt hat, wird es ziemlich kompliziert sie wieder zu reorganisieren, wenn man z.B. merkt, dass die Struktur doch nicht so gut ist. Zum einen können Referenzen zwischen Topics aus verschiedenen Ordnern kaputt gehen, zum anderen muss man im SVN aufpassen, dass man die Versionshistorie nicht verliert.

Fazit

Man kann auch topicorientiert schreiben und mit XML arbeiten ohne ein CMS zu benutzen. Eine Sache, die gern außer Acht gelassen wird, aber ich muss sagen, dass es nicht drauf ankommt welches Tool oder welche Standardisierungsmethode man verwendet – wichtig ist, was am Ende rauskommt!

Wenn man als Redaktion also kein Redaktionssystem zur Verfügung hat und trotzdem mit DITA arbeiten will, ist eine Verwaltung über Ordner und SVN meiner Meinung nach eine super Alternative.  Die Benutzung von SVN ist sogar absolut obligatorisch, wie ich finde.

Bei dieser Arbeitsweise müssen allerdings viele Dinge über Regeln und Workflows als „Denk dran“-Lösung abgedeckt werden, und die Erfahrung zeigt nun mal, dass man im Eifer des Projektgefechts nicht immer dran denkt.  Man kann zwar Skripte schreiben, die einem bestimmte Dinge abnehmen, aber am Ende muss man eben doch dran denken, das auch zu benutzen. Wenn sich mit der Zeit solche kleinen Fehler einschleichen, hat man irgendwann ein Problem. Man muss das Redaktionsteam außerdem ausführlich  schulen, denn die Grundfunktionen von SVN sind relativ schnell drin, aber gerade solche Dinge wie Tags/Branches/Merging sind nicht intuitiv.

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">

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 😉

Und es hat Bing gemacht!

Mich hat der Hype um Microsofts neue Suchmaschine Bing relativ kalt gelassen, weil…naja, seien wir mal ehrlich… wann hat einen zuletzt was aus diesem Softwarehause schon groß umgeworfen?

Nun mehren sich die Meldungen, dass der Marktanteil steigt und ich musste nun doch mal kurz reinschnuppern. „Und es hat Bing gemacht!“ weiterlesen

Spezialisierung: Eigene DITA-Attribute definieren

DITA bietet bereits einige Attribute, die schon sehr viele wichtige Dinge in der technischen Dokumentation abdecken: product, audience, platform seien da als Beispiele genannt.

Wenn es um sehr firmenspezifische Dinge geht, benötigt man hier schnell eigene Attribute. Für mich persönlich sehr wichtig, sind auch vorgegebene Attributwerte, weil eine vorgegebene Auswahl immer sehr viel weniger fehleranfällig ist.

Was bedeutet Spezialisierung?

In DITA nimmt man etwas Vorhandenes, also einen bereits vorhandenen Topictyp (z.B. Concept) oder ein bereits vorhandenes Attribut, und leitet davon seine eigene Version ab: man spezialisiert. Inbesondere in Bezug auf Topictypen ist wichtig zu wissen, dass man Festlegungen der DTD von der man ableitet, nicht „aufweichen“ kann. Wenn ein Element <hups> in der Ur-DTD zwingend erforderlich ist, kann man es in der Spezialisierungs-DTD nicht optional definieren.

Attribute spezialisieren

Es gibts 2 Arten von Attributen, die man spezialisieren kann: props (speziell für Filtern) und base (Sinn und Zweck hat sich mir noch nicht erschlossen…). Da ich mein neues Attribut zum Filtern des Contents benutzen möchte, benutze ich daher das props-Attribut.

Schritt 1: Attribut deklarieren
Ich werde nun ein Attribut definieren, das beschreiben soll, für welchen Hilfekontext das Element gilt: für die Hilfe im Web oder für die Hilfe in der Software.

  1. Zuerst erstelle ich eine Datei namens helpContextPropsDomain.ent mit folgendem Inhalt:



    Im ersten Teil lege ich den Namen des Attributs (help-context) fest und in meinem Fall auch 2 vordefinierte Werte (webpage, software).
  2. Ich speichere die Datei im dtd-Verzeichnis des DITA-OT ab.

Schritt 2: Attribut der DTD bekannt machen

  1. Nun öffne ich die concept.dtd und lege noch eine Sicherheitskopie von ihr unter anderem Namen ab Man weiß nie… ;).
  2. Unter dem Bereich DOMAIN ATTRIBUTE DECLARATIONS füge ich ein:

    SYSTEM "helpContextPropsDomain.ent"
    >
    %help-context-props-d-dec;
  3. Unter dem Bereich DOMAIN ATTRIBUTE EXTENSIONS erweitere ich :

  4. Unter dem Bereich DOMAINS ATTRIBUTE OVERRIDE erweitere ich :

    &ui-d-att; &hi-d-att; &pr-d-att; &sw-d-att;
    &ut-d-att; &indexing-d-att;&help-context-props-d-att;" >
  5. Diese Schritte müssen nun für alle Topictypen wiederhiolt werden, für die man das Attribut braucht.

Schritt 3: testen 🙂

  1. Ich erstelle eine XML-Datei auf Grundlage dieser DTD
  2. Ich füge das Attribut _help-context=“webpage“_ in ein-Element ein
  3. Ich jage das Dokument durch einen Validator – und wenn der nicht meckert, hat es funktioniert

Spezialisierung in XMetal DITA Edition
Der XMetal DITA Edition bindet ein DITA-OT ein. Wie es scheint benutzt er dieses ausschließich zum Generieren.
Die DTDs, die XMetal benutzt, liegen im Programmverzeichnis unter „…XMetaL 5\Author\DITA\DITA_OT_DTD\“<.

  1. D.h. die oben erstellten bzw. bearbeiteten Dateien müss dort hinein kopiert werden.
  2. XMetal neu starten
  3. Ein Concept anlegen
  4. Und sich freuen, dass man ein neues Attribut im Attribute Inspector sieht 🙂

Mehr zum Thema
In Eliot Kimbers Tutorial erfahrt ihr mehr zur Spezialisierung.