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.

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:

Ordnung muss sein #1

So lange man ohne CMS arbeitet, muss man auf die gute alte Ordnerstruktur zugreifen, um seine Dateien abzulegen. Einerseits bietet DITA einem natürlich einen Haufen toller Attribute mit denen man seine Topics filtern kann, andererseits kann man damit auf Dateisystemebene erst einmal nicht so viel anfangen.

Wieviel Ordnung brauchen wir?
Mit Ordnern neigt man gerne dazu tiefste Verschachtelungen zu bauen, was irgendwann ziemlich nervig zu navigieren sein kann. Außerdem gilt es zu bedenken, dass man bei DITA Topics auch keine scharfen Grenzen ziehen sollte, was ihre Zugehörigkeit anbelangt, denn man möchte sie ja vielleicht auch an verschiedensten Stellen wiederverwenden.

Also sollte man sich gut überlegen, welche Selektionskriterien, sprich: Ordnerebenen man tatsächlich benötigt.

Warum eigentlich nicht alles in einen Ordner schmeißen?
Keine gute Idee! Alle Topics zu 2 verschiedenen Produkten in einem Ordner können folgende Probleme aufwerfen:

  • Benennungschaos: Es kann durchaus sein, dass man Topics denselben Titel geben muss, aber der Inhalt verschieden ist, weil es sich um verschiedene Produkte handelt, bei denen das „Ordner bearbeiten“ unterschiedlich funktioniert. Natürlich könnte man dann sagen, dass man den Produktnamen in den Dateinamen des Topics mitaufnimmt, aber daraus resultieren dann ellenlange Dateinamen, die verwirren und schlimmstensfalls irgendwelche technischen Probleme auslösen (Zeichenbegrenzung).
  • schlechte Auffindbarkeit:Da haben wir also 5 Produkte und ziemlich wahrscheinlich auch mehrere Autoren dafür. Und dann sind da pro Produkt auch so ca. 100 Topics verfügbar. Auweia! Viel Spaß beim Suchen 🙂

Ich würde sagen, das spricht dafür, schon mal ein Metadatum Produkt zu definieren 🙂

Wichtige Metadaten
Selektionskriterien für die Doku können sein:

  • Sprache: Muss als DITA-Attribut vergeben werden, damit das DITA-OT variable Teile innerhalb des Topics entsprechend lokalisiert („Tip“, „Note“, „Short description“). Für einen Ordner spricht, dass je nach Sprachenanzahl die Topicanzahl wieder zu groß wird. Zudem sind die Screenshots je nach Sprache unterschiedlich
  • Produkt: Siehe oben. Allerdings muss man bedenken, dass es durchaus sein kann, dass es Topics gibt, die für mehrere Produkt gelten, aber nicht für alle.
  • Zielgruppe / Dokumenttyp: Dokumente, die an versch. Zielgruppen gerichtet sind oder auf versch. Dokumenttype, können trotzdem dieselben Dokuteile enthalten. Hier wird es schwierig zu unterscheiden, was man dann in welchen Ordner schmeißen würde.

Lösungsansatz

Auf diesem Level stehen als erstes Unterteilungskriterium das Produkt. Zusätzlich gibt es einen common-Ordner, der Topics enthält, die allgemein überall verwendet werden können / sollen.

Ein Schwachpunkt ist, dass es immer auch Topics geben wird, die für mehrere Produkte gelten, aber nicht für alle. Macht man solche Topics dann trotzdem in _common_ oder in einen der Produktordner? Gute Frage, deren Antwort ich in der Praxis hoffentlich bald beantworten kann

Das nächste ist die Sprache. Da die meisten Autoren in der Regel in nur einer Sprache arbeiten, sollte dieses Kriterium auch möglichst weit oben platziert sein.

Auf der nächsten Ebene folgen direkt die Dateien mit den Maps und dann jeweils ein topic-, ein images-, und ein output-Ordner. Mal sehen, wie sich das bewährt. Zumindest bin ich nicht die einzige mit diesem Ansatz 🙂

(Für das Protokoll: Ganz klar ist es am allerbesten, diese Verwaltungsebene einem CMS zu überlassen, weil man mit echter Metadaten-Vergabe viel flexibler arbeiten kann, als mit Ordnerstrukturen, die einem letztlich abverlangen, ein Topic absolut eindeutig irgendwo zuzuordnen. Aber CMSe sind noch nicht selbstverständlich in der Doku-Welt…)