Die Redakteuse

Kategorie: Softwaredokumentation

  • Wiederverwendbarkeit um jeden Preis?

    Das Prinzip der Wiederverwendbarkeit ist etwas, das die Software-Entwicklung und die technische Redaktion gemein haben: Redundanz ist böse 😉

    Deswegen macht es mir auch eher Spaß Entwicklern zu erklären, worum es bei meiner Arbeit vor allem geht: sie verstehen nämlich (meistens) ziemlich schnell, welche Probleme wir als Redakteure haben (und warum es Probleme sind!) und wie man die dann z.B. durch Verwendung von XML lösen kann.

    Die Kolumne „Be pragmatic, not dogmatic“ von Joachim Arrasz hat mich an einige Gedankengänge und Diskussionen zum Thema Wiederverwendung in der Doku erinnert. Die Essenz der Kolumne ist, dass man nicht um jeden Preis immer alles standardisiert und wiederverwendbar machen sollte. Denn am Ende könnten die Mühen dafür höher sein, als der eigentliche Nutzen.

    Ich habe so einen Fall z.B. selbst erlebt/produziert. Als ich entdeckte, dass man in DITA auch auf Map-Ebene wiederverwenden kann und so also z.B. einzelne Kapitel wiederverwenden kann, war ich im Wiederverwendungshimmel. Also habe ich die Hilfe, an der ich damals schrieb, sehr sorgfältig in etliche Maps unterteilt – ich könnte es ja mal wiederverwenden. Der Nachteil an der Sache war, dass es nicht so ganz einfach ist den Überblick über so viele Sub-Maps zu behalten. Man muss nach ein paar Wochen erst einmal wieder durchschauen, was wohin referenziert wird etc.

    Das Ende vom Lied war, dass ich bis zuletzt keine einzige dieser Maps wiederverwendet habe und mich eigentlich immer geärgert habe, wenn ich mit den vielen kleinen Maps arbeiten musste.

    Fazit

    Joachim sagt in seinem Artikel:

    Die „spätere mögliche Nutzbarkeit“ ist für mich sogar ein Showstopper. Dieses Argument habe ich schon so oft gehört, dass es mir in den Ohren klingelt. An dem Tag, an dem diese Wiederverwendbarkeit wirklich greifen würde, kann man immer noch das Refactoring anstoßen und sich zu diesem Zeitpunkt den Mehraufwand einholen.

    Ich denke, man muss einfach sorgfältig nach Anwendungsfall entscheiden wie stark man seinen Standards bis zum Ende folgt. Das spätere Umarbeiten (Refactoring) kann durchaus günstiger sein. In meinem Fall wäre es sinnvoller gewesen auf den konkreten Anwendungsfall zu warten und dann eben Zeit zu investieren, die Maps umzustrukturieren.

  • tekom 2010: Documentation for Software Engineers

    In meinem ersten Job wurde ich zur Betreuung der internen Dokumentation und des Firmen-Wikis eingestellt. Die Vision damals war, dass ich mal tüchtig aufräume und danach alle Abteilungen in der Firma tolle Dokumentation haben. Nun, das wäre super gewesen 🙂 Aber ich musste feststellen, dass das so einfach nicht ist. Es kommt zum einen darauf an, um was es sich für eine Abteilung handelt ( PR? Marketing?Personal? Entwicklung? Wenn ja, welche Richtung? etc), denn die Anforderungen sind dann natürlich unterschiedlich. Dazu hätte ich mich im Detail mit jeder Abteilung und ihrer Dokumentation auseinander setzen müssen. Eine Person alleine kann das für eine große Firma nicht schaffen – und: die Abteilungen müssen am Ende trotzdem auch immer noch selbst Dokumentation schreiben. Das war für die meisten die größte Überraschung damals 😉

    In dem Vortrag „Documentation for Software Engineers“ von Ulrike Parson habe ich nun einiges erfahren, wie man das Thema interne Dokumentation angehen kann. Und es hat meine oben erwähnten Erfahrungen bestätigt.

    Zielgruppen
    Auch bei interner Dokumentation ist es wichtig sich über die Zielgruppe Gedanken zu machen. Das wird bei diesem Thema oft vergessen – es ist ja „nur“ für intern. Die Zielgruppe ist hier der Software-Entwickler und seine verschiedenenen Ausprägungen. Frei übersetzt teilte Ulrike Parson sie wie folgt auf:

    • Den Praktiker:
      • will loslegen
      • benötigt Code-Kommentare, Code-Beispiele
    • Den Gründlichen:
      • liest zuerst einmal die Grundlagen
      • benötigt Hintergrundinfo zu API/Framework, Beschreibung allgemeiner Programmieraufgaben (Error handling, Lokalisierung &Co.)
    • Bedarfsleser
      • Liest bei konkreten Fragen nach
      • Benötigt Code-Kommentare, Hintergrundinformationen und Code-Beispiele

    Anhand dieser Zielgruppenanalyse schlüsselt sie dann auf, welche Dokumenttyen geliefert werden müssen, um diesen Anforderungen gerecht zu werden. Und auch wie sie geliefert werden müssen, z.B. als PDF oder Wiki mit Feedback-Funktion, Index etc.

    Die Rolle des technischen Redakteurs
    Ich habe von Entwicklern schon so oft gehört, dass sie endlich mal dokumentieren müssten oder endlich mal „gescheit dokumentieren“ müssten. Gleichzeitig hab ich mich immer gefragt: wie könnte ich dabei helfen? Immerhin heißt es doch auch „technische Dokumentation“, was ich studiert habe 😉

    Inwieweit der technische Redakteur die Entwickler beim tatsächlichen Dokumentieren unterstützen kann, hängt natürlich stark davon ab, wieviel Programmierwissen und -erfahrung er selbst hat. Aber es ist ununmgänglich, dass die Entwickler auch selbst dokumentieren – wer etwas selbst macht, weiß einfach am besten darüber Bescheid. Frau Parson hat sehr schön gezeigt, dass der Redakteur auch ohne selbst viel zu schreiben, doch sehr viel hier mitarbeiten kann.

    So können die Aufgaben des Redakteurs aussehen:

    • Zielgruppen- und Bedarfsanalyse
    • Dokumentationsworkflows erstellen
    • Terminologie erarbeiten, pflegen und bereitstellen
      • gerade in der Entwicklung lebt so manch uralter produktname ewig weiter
      • Missverständnisse untereinander werden vermieden
    • Neue Texte redigieren/korrigieren
    • Neue Texte evtl. schreiben
    • Strukur der Dokumentation entwickeln und überwachen
    • Dokumentvorlagen bereitstellen

    Und wenn man sich das mal genau anschaut, sieht man wieder, dass das ganz klassische Redakteursaufgaben sind. Nur ist der Fokus nicht so sehr darauf alles auch selbst zu schreiben, sondern viel mehr zu recherchieren, strukturieren, den Entwicklern eine Basis zu geben.

    Als praktisches Beispiel wurde abschließend noch ein Wiki gezeigt, das vor allem von den Entwicklern befüllt wird. Von der Redakteursseite wurde eine Grundstruktur angelegt und auch verschiedene Templates, damit die Entwickler nicht vor einer weißen Seite stehen und nicht wissen wo sie anfangen sollen. Der Redakteur überwachte nun die Entwicklung der Dokumentation und greift hier und da korrigierend ein. Zudem gibt es einen Freigabeprozess, so dass man auch wirklich nur qualitativ hochwertige Dokumentation publiziert.

    Für den einen oder anderen Software-Entwickler klingt das ganze vielleicht nach zu viel Reglement, aber ich habe schon zuviel schlechte und veraltete SW-Dokumentation gesehen und das klingt für mich nach einem plausiblen Weg aus der Misere.

    Fazit

    Ein hochinteressanter Vortrag (als PDF), der auch mal neue Wege für Redakteure aufgezeigt hat, die nicht in der klassischen Schiene liegen, aber am Ende doch perfekt auf das Skillset passen. Vielen Dank dafür! 🙂

  • 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

  • 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.

  • 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.

  • 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…

  • Task-Grenzen

    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:

    • Bild vom PC hochladen
    • Bild aus dem Web verlinken
    • Bild aus vorhandener Galerie einfügen

    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.

    • Bild vom PC hochladen
    • Bild aus dem Web verlinken
    • Bild aus vorhandener Galerie einfügen

    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.

    • Bild einfügen

    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:


    Um ein Bild hochzuladen, wählen Sie eine der folgenden Möglichkeiten:



    Um eine eigene Datei hochzuladen...
    ...


    Um eine Datei aus dem Web zu verlinken...
    ...


    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.

  • Breadcrumbs in DITA-XHTML

    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:

    1. Herunterladen.
    2. Das Verzeichnis qwcode.ancestors in das plugins-Verzeichnis im DITA-OT kopieren.
    3. Im DITA-OT-Verzeichnis eine Shell öffnen und ant -f integrator.xml eintippen.
      –> In der Datei dita2xhtml.xsl sollte das Stylesheet des Plugins nun referenziert werden.
    4. Im Verzeichnis qwcode.ancestors eine Shell öffnen und ant buildDemo eintippen.
      –> Hier sollten nun im Unterverzeichnis demo/xhtml die XHTML-Dateien generiert werden.

    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 🙂

  • Wiederverwendbarkeit von Maps & Cross-Media-Publishing

    Neben dem Single-Source-Publishing (aus einer Quelle baue unterschiedliche Dokumente, z.B. Admin-Handbuch und User-Quickstart) ist auch Cross-Media-Publishing ein wichtiges Schlagwort in der heutigen TR (aus einem Dokument baue verschiedene Outputs, z.B. PDF, HTML und CHM).  Beide Prinzipien finden sich auch in DITA wieder.

    Maps in DITA wiederverwenden

    Man kann in DITA ganze Maps wiederverwenden. Hierzu muss man im topicref einfach das Attribut format auf ditamap setzen:

    <topicref scope=“local“ format=“ditamap“ navtitle=“E-Mail“ href=“../E-Mail/E-Mail.ditamap“/>

    Die Topics dieser Map und ihre Hierarchie werden einfach in die Hierarchie der referenzierenden Map eingebaut, d.h. im Output kann man nicht mehr sagen, was auch welcher Map kam. Dies ist überaus praktisch, um beispielsweise nicht nur Wiederverwendung auf Topicebene zu machen, sondern eben auch auf bspw. Kapitelebene.

    Cross-Media-Publishing – wie ist die Realität?

    Die Crux beim Cross-Media-Publishing ist: das was im Print funktioniert, muss noch lange nicht online funktionieren. Und umgekehrt natürlich.

    Hilfemedien unterscheiden sich durch mehr als das Dateiformat. In Online-Hilfen muss man z.B. viel mehr verlinken.

    Ich habe nun gerade eine Map angelegt, die sehr stark auf den HTML-Output ausgelegt ist. Ich will dort beispielsweise kein komplettes Inhaltsverzeichnis, weil mir das im Onlineformat zu viel ist. Ein Inhaltsverzeichnis mit 70 Topics ist einfach zuviel (und ein hübsches JavaScript-Aufklapp-Inhaltsverzeichnis ist hier nicht angebracht). Daher habe ich sehr viele Topics auf „toc=no“ gesetzt. Die Beziehungen werden für den Nutzer über die hierarchischen Links und related Links dann schon abgedeckt.

    Nun ist die Map fertig und mir wird klar, dass sie so nicht wiederverwendbar ist.  Es ist eine reine HTML-Map und wenn ich ein PDF mit einer ähnlichen Struktur bauen möchte, werde ich eine neue Map bauen müssen, was aber zu Redundanz führt (Böse, böse! BÖSE!). Oder ich ändere je nach Output jedes Mal die toc-Attribute (Blöd, blöd! BLÖD!).

    Fazit?

    Ich muss schauen, wie sich das entwickelt. Aktuell steht es nicht in Aussicht, dass ich ein PDF benötige, aber in der Informationsarchitektur muss ja ein wenig vorausschauen und ich sehe schon förmlich, wie die PDF-Wolke sich am Himmel zusammenbraut (oh, nicht das falsche Vorstellungen aufkommen: ich sehe meine Auftraggeber nicht als Götter an 😉 ). Leider hab ich bisher nur Schilderungen gefunden, die meine beiden Optionen bestätigen.

    Irgendwie muss ich diesen Grat zwischen Cross-Media-Publishing und trotzdem „passend für das tatsächliche Medium“ noch finden. Hmmm.