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)
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:
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 😉
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" >
<
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>
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 🙁
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 .
[xml]<task id="d262.dita">…</task>[/xml]
Also geb ich hier einfach das href-Attribut des Parents aus, das ja den Dateinamen beinhaltet. Sehr einfach, juhu!
[xml]<xsl:value-of select="../@href"/>[/xml]
Aber Moment im Endergebnis der Transformation finde ich plötzlich das hier
[xml]
<topic id="t_Duda.dita">
<title>Duda</title>
<topic parentid="t_Duda.xml" id="t_Dida.dita">
[/xml]
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:
[xml]<param name="dita.extname" value="dita"/>[/xml]
Und schon hat es gepasst!
[xml]
<topic " id="t_Duda.dita">
<title>Duda</title>
<topic parentid="t_Duda.dita" id="t_Dida.dita">
[/xml]
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 😉
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
Ich füge noch hinzu:
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…
Beim Texten von Tasks gibt es etwas, was mich als Redakteur von Software-Doku seit den Anfangstagen als TR regelmäßig verrückt macht: wo hört ein Task auf und wo beginnt der nächste? Speziell bei Handlungen, die im Großen und Ganzen dasselbe Ziel haben, aber die man auf verschiedenen Wegen erreichen kann.
1 Handlung = mehrere Varianten
Ein gängiges Beispiel ist das Einfügen von Bildern, z.B. in ein Blog oder eine Website.
Ziel: Bild in den Artikel einfügen
Möglichkeiten zur Zielerreichung:
Die Handlungen sind in den ersten Schritten typischerweise identisch, aber unterscheiden sich dann in den meisten folgenden Schritten. Nur das Ziel ist am Ende dasselbe: ein Bild wurde eingefügt. Ich bin nie so ganz schlüssig, was ich in solchen Fällen tun soll.
Option 1:Rigoroses Splitten
ich teile das ganz rigoros in drei Topics auf. Der Nutzer sieht ganz spezifisch an der Topic-Überschrift um was es geht.
Das Problem ist, dass ich auf diese Weise ganz schön viele Topics produziere, die den Nutzer fast erschlagen. Zudem gibt es auch Nutzer, die nur wissen, dass sie ein Bild einfügen wollen, aber mit den drei Optionen einfach so nichts anfangen können. Und prinzipiell sucht wahrscheinlich auch ein erfahrener Nutzer eher nach „Bild einfügen“ als nach „aus dem Web verlinken“.
Option 2: In ein Topic verpacken
Es gibt einen Ort an dem der Nutzer nachschaut – bingo, da sieht er alles was zu dem Thema wissen muss.
Das Problem ist, dass man so unter Umständen ganz schön lange Topics produziert – zudem kann man es kaum in die SITA-Struktur packen. Es gibt zwar Handlungsvarianten (choice), aber die beziehen sich meist auf einen Handlungsschritt, und nicht einen ganzen Handlungsstrang. Sowas wäre mir am liebsten:
Aber das lässt DITA nicht zu. Mir ist auch klar warum: damit fällt es einem leichter mehrere Topics in eins zu verpacken. Und man will ja immer nur ein Thema pro Topic. Dummerweise ist das Leben nicht immer so einfach. Hier würde ich mir zumindest mehr Flexibilität wünschen.
Fazit
Hält man sich streng an die DITA-Informationsarchitektur kann man eigentlich nicht anders als das auf 3 Topics zu splitten. Aber aus Nutzersicht gefällt es mir nicht.
Der Name Breadcrumb-Navigation wurde in Anlehnung an das Märchen Hänsel und Gretel der Brüder Grimm gebildet, in dem die in den Wald geführten Kinder Brotkrumen (englisch breadcrumbs, plurale tantum) auf den Weg streuen, um den Weg zurück zu finden (PediaWiki)
Mir geht es speziell um die „Location-Breadcrumbs“, d.h. ich möchte, dass in meiner HTML-Hilfe sichtbar ist, wo in der Hierarchie sich der Nutzer gerade befindet.
Ein sehr klassisches Instrument in der Nutzerführung, das aber lustigerweise in dem Standard-XHTML-Output gar nicht drin ist.
Nachdem ich etwas recherchiert habe, bin ich recht schnell auf ein relativ frisches Plugin gestoßen, das genau das macht: Ancestors
So sieht eine Topic-Seite in HTML dann auch aus, wenn man sie generiert:
Installation
Die Installation ist denkbar einfach:
Das ganze hat bei mir echt gut geklappt und daher spreche ich eine eingeschränkte Empfehlung aus. Die Einschränkung folgt auch sofort.
Bug bei Verwendung von reltables
Aktuell werden leider bei allen Topics, die in Reltables referenziert werden, die Breadcrumbs falsch dargestellt, so wie in diesem Beispiel, in dem die Startseite „Index“ zweimal verlinkt wird. Das zu fixen ist sicherlich kein Hexenwerk, aber ich habe gerade keine Zeit… Wenn das aber gefixt ist, empfehle ich absolut uneingeschränkt 🙂
Mit den so genannten Relationship tables (reltable) kann man die Beziehungen zwischen Topics definieren. Hiermit implementiert man Verlinkungen, die nicht durch die Hierarchie (oder die anderen collection-types) festgelegt ist. (mehr …)
Ich habe bereits vorgestellt, welche Möglichkeiten des manuellen Verlinkens es gibt. Wie gesagt, erschwert diese Methodik die Wiederverwendung eines Texts. Da Wiederverwendung jedoch einer der Kernpunkte von DITA ist, gibt es natürlich auch hier Mittel und Wege. Und zwar indem man die Verlinkungregeln in die Maps auslagert. So kann man auch nur das verlinken, was in der Map drin ist und läuft nicht Gefahr tote Links zu erzeigen.
(mehr …)
