Die Redakteuse

Schlagwort: DITA

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

  • Links in DITA #1

    Der Link ist essentieller Bestandteil der Online-Welt. Gerade bei der Topicorientierung, in der Information quasi auseinandergerissen ist, ist er die beste Navigationsmöglichkeit für den Leser und stellt einen Kontext her.

    DITA ermöglicht einem einerseits manuell Links zu setzen oder sie automatisiert setzen zu lassen, indem man vorher den Beziehungsstatus definiert.

    Heute gibt es erst einmal etwas zu den Links, die man als Redakteur selbst direkt einfügen kann.

    <xref> – Inline-Links
    Diese Links setze ich manuell mitten im Textfluss. Etwa so wie diesen hier. Dieses Vorgehen ist eigentlich allgemein bekannt.
    Im Code sieht es so aus:

    hier

    Verlinken kann man alles von anderen Topics bis hin zu Webseiten (nur bei Links von generierten PDFs auf Online-PDFs muss man bei Verwendung des FOP aufpassen).
    Generell ist das Verwenden von Inline-Links aber eigentlich nicht so toll:

    • sie unterbrechen des Lesefluss und die Aufmerksamkeit des Nutzers. Will man den Nutzer wirklich mitten im Task in einen völlig anderen Kontext schicken? Eigentlich nicht. Höchstens wenn es sich um eine Handlungsvoraussetzung handelt.
    • ein Topic ist durch einen Inline-Link in der Regel schlechter wiederverwendbar. Verwendet man es wieder, könnte der Link kaputt gehen, weil das Linkziel in diesem neuen Kontext nicht vorhanden ist.

    <related-links>
    In der manuellen Variante der „Related links“ fügt man den Tag <related-links> ein und setzt die Links in einzelne <link>-Tags oder in eine <linklist>. Das Gute an diesem Tag ist, dass er am Ende des Topics gesetzt wird, also den Nutzer nicht aus dem Kontext reißt. Aber auch in dieser Option steckt der Nachteil, dass die Wiederverwendung des Topics eingeschränkt wird.

  • DITA und XMetal

    Und jetzt erst finde ich diese Präsentation von Simon Bate (Scriptorium)! Meine Güte, da hätte ich mir einiges an nerviger Recherche sparen können.

    Aber ich will mein Wissen natürlich brav weitergeben: also holt euch Popcorn, was zu schreiben und stellt das Radio aus. Hier wird es wirklich interessant und praxisbezogen 🙂

    XMetaL DITA Workshop

    View more presentations from Scriptorium.

    Hierbei muss ich erwähnen, dass ich Slideshare einfach großartig finde. Im deutschen Raum scheint es noch gar nicht sehr verbreitet zu sein. Vielleicht sollte man das auch mal den Leuten der tekom zeigen. Es wäre ja viel cooler, die Tagungspräsentationen hier zu posten, als irgendwo in den Irrungen&Wirrungen der tekom-Webseite (die sich nicht gerade durch einen großen information scent hervortut). Und ich glaub auch fast, dass man hier auch mehr Hits erhalten würde.

  • DITA-Output filtern mit XMetal

    Wiederverwendung und Varianten
    Das Filtern wird in Zeiten der Wiederverwendung früher oder später notwendig. Man hat beispielsweise ein Produkt, dass es in einer Light-Version und einer Vollversion gibt. Natürlich werden sich hier die Hilfetexte zum größten Teil überschneiden – bis auf die kleinen Ausnahmen, wo dann in der Vollversion hier noch ein Schritt weniger ist und dort eine Option mehr verfügbar. Man hat also eine Wiederverwendungsquote von 90%, aber was tun? Die Hilfetopics nun zweifach vorhalten? Ne, da sträuben sich jedem guten Redakteur die Haare. Redundanz, nein danke!

    Nun, wie wär’s, wenn man einfach alle Varianten in eine Datei schreibt und die Teile, die nur für ein Produkt gelten mit einem Attribut versieht? Und dann beim Generieren einen Filter definiert, der nur Teile generiert, die einen bestimmten Attributwert enthalten? Klingt cool – isses auch!

    Attribute in DITA
    Es gibt für DITA schon einige fest definierte Attribute, die man an fast jeden Tag vergeben kann. Es sind gängigen Attribute nach denen man in der Doku filtert und für die man frei Werte definieren kann:

    • product
    • audience
    • platform
    • outputclass (erst ab DITA OT 1.4 unterstützt)

    Zu guter Letzt gibt es das otherprops-Attribut, das so ziemlich alles enthalten kann. Eine Art Auffanglager für den Rest sozusagen.

    DITA-Attributvergabe im XMetal

    Wir nehmen uns nun ein Beispiel, in dem ein bestimmter Handlungsschritt nur in der Print-Hilfe auftaucht und in der Online-Hilfe nicht, weil die Online-Hilfe kontextbasiert ist und ein Zwischenschritt wegfällt, der aber in der Print-Version nötig ist.

    Eigentlich sollte man dazu ab DITA 1.4 das Attribut outputclass verwenden, da ich aber noch auf DITA 1.3 arbeite, werde ich also das otherprops-Attribut verwenden. Ich markiere den <step> und  schreibe im Attribute Inspector einfach den Wert hinein nach dem ich filtern möchte.

    Der Nachteil hierbei ist, dass je nach Attributwert einem anderen Redakteur nicht unbedingt von Namen her sofort klar ist, nach was hier gefiltert wird. Wenn ich z.B. handbook als Wert eingebe, kann das einerseits bedeuten, dass ich für den PDF-Output etwas filtern möchte (es also eine technische Bedeutung hat) oder aber für den Dokumenttyp „Handbuch“ (was dann eher inhaltliche Bedeutung hat).

    Filterregeln in XMetal anlegen

    Hierzu muss man folgende Datei öffnen: c:\Programme\XMetaL 5\Author\Conditional Text\configs\ct_config.xml

    Hier kann man nun seine Attributwerte definieren und festlegen, wie diese in der Filterauswahl angezeigt werden. Ich habe hier den Attributkomplex zu otherprops bearbeitet. Für jeden Attributwert definiert man einen <value>-Tag, in name steht der Attributwert und in title steht der Anzeigename in der Filterauswahl.

    ´[....]

    Filterregeln auswählen

    1. Auf File > Generate Output from DITA map klicken.
    2. Im Dialog auf Show/Hide Conditional Text klicken.
    3. Hier kann man nun auswählen, welche Filterkriterien für den aktuellen Output gelten sollen.
      Ich will nun beispielsweise eine Online-Hilfe generieren, d.h. der <step>, der nur für Handbücher gilt, soll nicht generiert werden. Also klicke ich das Filterkriterium Onlinehelp an. Es wird alles generiert, was keinen Wert für dieses Attribut hat oder eben genau diesen Wert, d.h. der <step> mit dem Attributwert Handbook wird hier nicht generiert werden.

    Ergebnis
    Am Anfang steht also dieser Code:

    Öffnen Sie das Programm.

    Klicken Sie auf

    DateiNeu

    Editieren Sie die Datei.

    Und am Ende dieser Text:

    1. Klicken Sie auf Datei > Neu.
    2. Editieren Sie die Datei.

  • Gelesen: DITA – Der neue Standard für technische Dokumentation

    Bisher sind die Informationsquellen bzw. die Literatur zu DITA eher rar, im Endeffekt bleibt man beim User-Guide und der Yahoo-Group hängen und sammelt sich dort alles irgendwie zusammen.

    Nun bin ich endlich dazu gekommen mir das erste deutschsprachige Buch rund um DITA zu bestellen und zu lesen: DITA – Der neue Standard für technische Dokumentation von Johannes Hentrich. Frau Closs Buch konzentriert sich ja mehr auf Topicorientierung als auf DITA, auch wenn das natürlich gut zusammenpasst.

    Was steht zu DITA drin?

    Es ist so ziemlich alles drin, was man über DITA wissen muss:

    • Welche Philosophie dahinter steht,
    • wie es funktioniert,
    • was das Open Toolkit ist,
    • wie man den Output, also die Stylesheets, verändert,
    • wie man mit DITA wiederverwendet und filtert,
    • welche Editoren es gibt,
    • warum ein CMS Sinn macht…

    Sehr gut fand ich die Anwendungsbeispiele. Erst hier hab ich mal so richtig kapiert, was chunking eigentlich bedeutet (und das werde ich hier sicherlich mal noch in eigenen Worten wiedergeben). Ein bisschen überflüssig fand ich, dass sehr viele Dinge wiederholt wurden, z.B. was Topicorientierung bedeutet…

    Unnötige Basics

    So gut ich den Umfang zu DITA fand, so schlecht fand ich, dass das Buch gleichzeitig noch versucht einen Rundumschlag in Sachen „Technische Redaktion“ zu machen. Das macht das Buch ein bisschen unausgewogen in seiner Zielsetzung. Und mal ganz ehrlich – wenn man sich in DITA reinkniet und bereit ist Stylesheets u.ä. anzufassen, dann muss man hier nicht bei den Binsenweisheiten der TDOKU anfangen. Ja, ich weiß, dass Standardisierung wichtig ist und Wiederverwendung sowieso. Wer es nicht weiß, hat den falschen Beruf gewählt oder sollte erst einmal bei den echten Basics-Büchern anfangen.

    Rechtschreibprüfung?

    Was mein Redakteusenauge sehr genervt hat, waren die zahlreichen Tippfehler und auch Satzfehler in dem Buch. Mindestens alle drei Seiten war irgendetwas falsch geschrieben oder umgebrochen. Für das nächste Buch empfehle ich hier einen sorgfältigeren Lektor. Bei so einer kritischen Zielgruppe MUSS da alles stimmen.

    Fazit

    Für Leute, die sich in DITA reinknien wollen, ist das Buch auf jeden Fall das Richtige. Die unnötigen Kapitel kann man ja zum Glück einfach überspringen 😉 Ansonsten bekommt man alle Infos, insbesondere auch die zum Toolkit kompakt und gut dargestellt und erklärt. Dieser Teil hat mich persönlich sehr überzeugt.

    Für Anfänger in der technischen Doku hingehen enpfehle ich das Buch eher nicht, da die Kapitel, die richtig in die DITA-Materie reingehen, hier meiner Meinung nach eher abschrecken / überfordern.

    Zum Abschluss muss ich noch erwähnen, dass ich die Behauptung, dass gute Stichwortverzeichnisse bei Büchern kaufentscheidend sind, sehr witzig fand. Das trifft bei mir allerhöchstens auf Lexika und Telefonbücher zu 😉 Ansonsten ist in der Regel sicherlich das Inhaltsverzeichnis der ausschlaggebendere Punkt, nicht umsonst stellt amazon bei vielen Büchern das Inhaltsverzeichnis online zur Verfügung. Keine Frage Indizes sind ein wichtiges Navigationsmittel, aber meist bemerke ich die erst weit nach dem Kauf.Umso lustiger fand ich es aber mir auf diese Aussage hin mal den Index dieses Buchs anzuschauen und etwas darin zu suchen. Es sei nur soviel gesagt: Er sollte nicht eure Kaufentscheidung beeinflussen. Denn eigentlich lohnt sich das Buch 🙂

  • DITA-Referenz in der Praxis: shortdesc vs context

    Wenn man mit DITA anfängt, hat man zuerst das Gefühl: „Wow, ich muss nichts mehr selbst erfinden. Alles ist schon da! Woohooo!“ Kaum schreibt man ein bisschen länger, stellt man fest, dass es immer wieder Fälle gibt, in denen die DITA-Referenz nicht so eindeutig ist, wie man sich das wünscht

    Ich habe mich beospielsweise immer schwer getan die Funktion der Tags shortdesc und context innerhalb eines Tasks zu trennen. Beide sind dazu da dem Nutzer zu sagen, was der Sinn und Zwecks des vorliegenden Topics ist. Bisher habe ich context nicht genutzt, aber so langsam komme ich dahinter, wie ich es nutze.

    <shortdesc>

    Die shortdesc soll das zentrale Ziel des Topics beschreiben, aber ganz kurz sein, damit man sie z.B. in Inhaltsverzeichnissen als Kurzbeschreibung mitliefern kann. Es macht aber auch nicht viel Sinn in der shortdesc einfach nur den Titel des Topics zu wiederholen, wie es in Hilfe nur allzu häufig passiert:

    In diesen absolut selbst erklärenden Fällen lasse ich es auch weg, aber meistens versuche ich doch irgendwie, etwas reinzuschreiben. Auch in diesem Beispiel ist mir etwas eingefallen, was dem Nutzer in einer Kurzübersicht einen Mehrwert bringt und zwar indem es ihm schon einen Hinweis auf das Ziel gibt: „Links auf oft genutzte Webseiten speichern.“

    <context>

    Im context kann man mehr Informationen zum Topic geben. Und zwar wann und warum der Nutzer einen bestimmten Task ausführen kann / soll / muss. Gleichzeitig muss man hier ab auch aufpassen nicht so viele Hintergrundinformationen reinzupacken, dass man fast schon ein Concept draus machen könnte.

    Je nach Fall ist das für mich auch der Ort nützliche Anwendungsbeispiele zu nennen.

  • XHTML-Output anpassen #2 – Wie mache ich einen Override?

    Ich habe nun damit angefangen Anpassungen vorzunehmen.

    Im Groben sind dazu folgende Schritte notwendig:

    1. Plugin-Verzeichnis und Dateien anlegen.
    2. Plugin integrieren.
    3. XSL anpassen.

    Plugin-Verzeichnis und Dateien anlegen

    Dazu habe ich unter DITA_OT/demo ein Verzeichnis meinxhtml für meine Overrides angelegt, d.h. hier liegen meine Anpassungen für den XHTML-Output. Für DITA ist das einfach ein Plugin.

    In diesem Verzeichnis befindet sich ein Ordner mit meinen XSL-Dateien und die plugin.xml. In dieser Datei muss man dem DITA-OT sein Plugin quasi bekannt machen. Das sieht dann so aus:

    Plugin integrieren

    1. Hierzu öffnet man sich eine Konsole im DITA-OT-Verzeichnis und führt folgenden Befehl aus: ant -f integrator.xml
      Ob das wirklich geklappt hat, kann man in der Datei xsl/dita.2xhtml überprüfen. Dort sollte die XSL-Datei nun über ein <xsl:import> referenziert werden.

    XSL anpassen

    Jetzt kommt der wirklich spannende Teil. Wie schon erwähnt, wird das meiste über die Datei dita2htmlImpl.xsl gemacht. Wenn ich also nun etwas Bestimmtes modifizieren will, z.B. dass nach dem Titel einer Note kein Doppelpunkt kommt, gehe ich wie folgt vor.

    1. Ich schaue über Firebug in den Quelltext des Outputs, um zu sehen, ob der Bereich irgendwie besonders ausgezeichnet ist. Im Falle der Note sehe ich, dass der Note-Title in einem span-Tag steht und mit der CSS-Klasse notetitle ausgestattet ist.
    2. Über diese Hinweise finde ich dann in der XSL-Datei das entsprechende XSL-Template für diesen Bereich:
    3. Ich kopiere nun das komplette Template in meine mein_xhtml.xsl.
    4. Um den Doppelpunkt zu entfernen, lösche ich die entsprechenden Anweisungen. In diesem Beispiel also: 

    5. Diese Änderung speichern.
    6. Output generieren.
      Und nun sollte der Doppelpunkt verschwunden sein. Leider muss man den Doppelpunkt für alle Note-Typen entfernen, die es gibt, also für Tipps, Warnungen etc.

    Hiermit lässt sich schon mal sehr viel machen. An die Grenzen der Overrides kommt man beim OT 1.3, wenn es um die Anpassung des Inhaltsverzeichnisses geht. Hier funktionieren Overrides nämlich leider, leider nicht. Doch dazu ein anderes Mal mehr 🙂

  • DITA-Texte anpassen

    Ja, die Zeit der Anpassung ist da 😉

    Mit dem OT kommt ja schon ein Satz an Texten mit Übersetzungen mit. Natürlich passen einem da so manche Texte nicht wirklich und man möchte sie ändern. Oder man möchte vielleicht noch Texte hinzufügen, so wie ich einen umfangreichen, firmenspezifischen Copyright-Text.

    Ich habe hier bisher in der Not die Dateien in DITA_OT/xsl/common entsprechend geändert. Hat funktioniert, hat mir aber nicht so richtig gefallen, weil es eben Original-OT-Dateien sind, die ich editiere.

    Daher fand ich das StringsPluginExample aus dem Files-Bereich der DITA-Yahoo-Group richtig genial und habe auch gleich versucht, das zu installieren (Anleitung). Man kann damit seine eigenen String-Dateien definieren, die dann die des OTs einfach überschreiben. Eigentlich eine einfache Sache…!

    1. Leider ist nach der Installation beim Generieren einfach gar nichts passiert.
    2. Irgendwann stellte ich fest, dass so ein Override erst ab Version 1.4.2 des OT möglich ist.
    3. Kurz darauf versuchte ich bei meinem XMetal nach Anleitung ein OT-Upgrade durchzuführen (und zwar indem man die Variable DITA_OT_DIR auf das Verzeichnis der neuen version setzt). Hat nicht funktioniert.
    4. Dann habe ich wieder festgestellt, dass dieser Parameter mit der OT-Version 1.4.2 nicht funktioniert, aber dass JustSystems einen Patch anbietet.
    5. Mist, der Patch darf nur auf XMetal 5.1 angewandt werden. Und wenn man eine frühere Version hat, soll man doch bitte in Betracht ziehen erst einmal ein Upgrade von XMetal zu machen.

    Kurz: ich mache alles wie bisher und kommentiere meine Änderungen brav. Allerdings finde ich es sehr bedenklich, dass ich ein Tool habe, mit dem ich nicht mal eben so ein Upgrade meiner Architektur durchführen kann. Klar, wenn ich nur in Notepad++ arbeite und über die Kommandozeile publiziere, ist das eher problemlos 😉

    Ich frage mich, ob man das Problem z.B. auch mit Arbortext hat?

  • XHTML-Output anpassen

    Jeder, der mit DITA anfängt, kommt schnell an dem Punkt an dem er das starke Bedürfnis hat, den Output an das eigene Layout anzupassen. Die Standardlayouts im OT sind, sagen wir mal, sehr nüchtern oder auch eher 0.5 als 2.0 😉

    Und in einer Firma will man natürlich Logos und allerlei Schnick-schnack einbauen.

    So, und ich will nun beginnen einen schönen XHTML-Output zu bauen und habe nun damit angefangen die XSL-Stylesheets auseinanderzunehmen, um zu verstehen, was eigentlich wo passiert.

    Schöne Overrides

    Sehr interessant fand ich diese schöne modulare (oh ja, das Wort das jeden technischen Redakteur jauchzen lässt!) Vorgehensweise die eigenen Anforderungen einzubinden. Robert Anderson zeigt in diesem Webinar, dass man eigene Anpassungen immer auslagern sollte, seien es eigene Spezialisierungen oder eben auch „nur“ eigene Layoutdefinitionen. So muss man beispielsweise später keine Bedenken haben, wenn man ein Upgrade auf eine neue OT-Version machen möchte: man hat eben keine Original-OT-Dateien bearbeitet, sondern nur eigene, die in die OT-Dateien nur eingebunden werden.

    Das OT bietet dem User die Möglichkeit sogenannte Overrrides zu definieren, die die Standard-Einstellungen mit den selbst definierten überschreiben.  Diese Overrides werden in Plugins ausgelagert. In der Datei _dita2htmlImpl.xsl_ sind dafür ab Zeile 4166 Templates vorgesehen und zwar für Header, Footer, die head-section,Angaben zu CSS-Dateien und Skripten.

    Eine sehr einleuchtende Vorgehensweise, die schön modular und damit leichter pflegbar ist.

    Ich benutze ja XMetal und hier wurde eine solches Layoutmodul schon mitgeliefert. Wer einmal den Output Single HTML file advanced testet, wird sehen, dass da ein JustSystems-Design hinterlegt ist. Die entsprechenden Dateien findet man je nach Installation ungefähr hier: c:\Programme\Gemeinsame Dateien\XMetaL Shared\DITA_OT\demo\xhtmls.

    Hässliche Overrides

    Umso seltsamer fand ich, dass für einfache Anpassungen im OT-User-Guide ein ganz anderes Vorgehen geschildert wurde: einfach das XSL aus dem OT kopieren, entsprechend ändern und unter anderem Namen abspeichern. Und dann den Output über dieses eigene Stylesheet erzeugen (Quelle). Nun ja, klar das geht. Aber irgendwann wird es nahezu unmöglich sein herauszufinden, was Original-OT ist und was man selbst verbrochen hat. Und Updates sind dann sehr aufwändig.

    Schön oder hässlich? – Kommt drauf an

    So wie ich das bisher verstehe, ist „hässliche“ Variante erst sinnvoll, wenn ich den XHTML-Output komplett anders haben möchte. Dann verbiegt man sich komplett, indem man alle Änderungen in Overrides auslagert. Ich habe beim TWiki genau diese Erfahrung nämlich gemacht. Man kann dort die Default-Styles mit eigenen Styles überschreiben und den Rest übernehmen. Bei einem Update haben die selbstdefinierten Styles damals nicht mehr gut funktioniert, weil man sich in zu vielen Punkten auf Default-Styles verlassen hat und die aber beim Update signifikant verändert wurden.

    Los geht’s

    Bei mir wird leider nicht bei einigen „billigen“ Styleverbesserungen bleiben, sondern ich will strukturell auch einiges anders haben als im Standard-Output und daher versuche ich mal es in einem neuen Stylesheet auszulagern. Es wird spannend 🙂

  • Ordnung muss sein #2 – SubVersion

    So, ich habe nun eine tolle Ordnerstruktur.  Beim Schreiben mit DITA produziert man viele, viele Topics, also ganz viele einzelne Dateien. Diese Arbeitsweise ist geradezu prädestiniert dazu, die Arbeit auf mehrere Redakteursschultern zu verteilen.

    Tja, und was sagt man gerne über viele Köche und ihren Brei? Ja, man muss die Zusammenarbeit irgendwie steuerbar und kontrollierbar halten. Wenn man nun kein CMS hat, um einem die Verwaltungsarbeit abzunehmen, sollte man zumindest eine Sache auf jeden Fall verfolgen:  Versionsverwaltung. Und damit meine ich keine täglichen Kopien des Arbeitsordners auf irgendein Laufwerk! Das nimmt auf die Dauer zuviel Speicherplatz ein und man hat bei mehreren Autoren keinen Überblick wer was wann editiert hat. Ein paralleles, effizientes Arbeiten ohne Versionsfehler ist dann wirklich schwer.

    SubVersion (SVN) – eine kurze Einführung

    Hier kommt nun SVN in Spiel.  SVN ist eine Open-Source-Software mit der man die Versionen von Dateien und Ordner verwalten kann. Sie kommt vor allem in der Software-Entwicklung zum Einsatz. Jede Änderung einer Datei / eines Ordners wird in einer Version festgehalten, so dass man auch immer wieder auf alte Versionen zurückgehen kann, falls man in der neuen nur Müll produziert hat. Zudem kann über die Versionshistorie auch verfolgen, welche Änderungen gemacht wurden, wer sie wann gemacht hat und, wenn es Kommentare gibt, auch warum.

    SVN funktioniert so, dass man ein zentrales Verzeichnis hat, in dem die allgemein gültige Version der verwalteten Inhalte steckt, in meiner Branche also  die DITA-Dateien.  Das ist das sog. Repository.

    Nun kann sich jeder, sofern Zugriffsrechte vorhanden, eine lokale Arbeitskopie dieses Repositories auf seinen Arbeitsplatzrechner ziehen (auschecken) und anfangen daran zu arbeiten. Das Schöne hierbei ist, dass dies viele Kollegen auf einmal tun können und so parallel an derselben Doku arbeiten können. Am Ende des Tages Kollegin R. mit ihrer Arbeit hochzufrieden und möchten diese in das zentrale Repository laden. Bei SVN heißt das committen.

    Sobald die Änderungen im Repository sind, kann jeder andere Kollegen updaten, sprich: seine lokale Arbeitskopie aktualisieren und hat Kollegin Rs Änderungen automatisch drin. Eine feine Sache, so ist jeder auf dem aktuellen Stand.

    Aber oh weh – als Kollegin T versucht, ihre Arbeitskopie zu aktualisieren, um die Änderungen von Kollegin R in ihre Kopie zu übernehmen (dieser Vorgang des Zusammenführens heißt mergen), wird ihr angezeigt, dass es einen Konflikt gibt. Das heißt soviel wie, dass Kollegin R und Kollegin T an derselben Stelle eine Änderung vorgenommen haben und SVN natürlich nun nicht entscheiden kann, welche Änderung die bessere ist. Deswegen wird es Kollegin T auch angezeigt, damit sie diesen Konflikt irgendwie auflösen kann.

    Ordnung in SVN

    Im Prinzip könnte ich meine Ordnerstruktur direkt einchecken und damit arbeiten. In SVN gibt es jedoch auch noch ein paar Nützlichkeiten, was die Dateiorganisation anbelangt.

    • Tags: Damit wird mir ermöglicht einen bestimmten Stand mit einem Stichwort, also einem Tag, zu versehen, um später die jeweiligen Versionsstände aller beteiligten Dateien, die beispielsweise zu einem bestimmten Release gehören, auf einen Schlag wiederzufinden. Ein Beispiel für einen Tag wäre also die Releasenummer der Software, die man dokumentiert.
    • Branches: Nun kann es passieren, dass man schon längst wieder an der Doku für das nächste Release arbeitet, und es erreicht einen die Nachricht, dass es in der Version für das letzte Release einen happigen Fehler gab, der für die Kunden, die es nutzen, gefixt werden muss. Das ist der Punkt, wo man anfangen würde einen neuen Entwicklungszweig (branch) aufzumachen. Man arbeitet also an einer Stelle noch am Handbuch für das alte Release (im branch) und an der anderen für das neue (im sog. trunk, dem Hauptentwicklungszweig). Das Schöne ist auch, dass es die Möglichkeit gibt, diese zweige zusammenzuführen. Um beim genannten Beispiel zu bleiben: der Fix im alten Release könnte auch für das neue Release vonnöten sein. Hier könnte man dann wieder mergen.

    DITA-Doku in SVN reloaded

    Das heißt, die Ordnerstruktur mit SVN könnte also so aussehen: