Monat: November 2008

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:

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

Auf Tom Johnsons Blog gibt es gerade einen guten Artikel zum Thema „Vom Literaturstudium zur Technischen Redaktion“, den ich so ziemlich unterschreiben kann 🙂

Von der Goethe-Bibliographie zum Software-Handbuch

Wie schon früher erwähnt komme ich ja ursprünglich von der Germanistik und bin absolut überzeugt, dass ein solcher Hintergrund bestens auf die Dokumentation vorbereitet. Und zwar weniger wegen dem Schreiben, sondern viel mehr wegen dem Recherchieren, Analysieren und Strukturieren. Damals waren das für mich die Grundlagen, um eine gute Hausarbeit, einen guten Aufsatz über ein Thema zu schreiben.

Und wie Tom bemerkt, unterscheiden sich Hausarbeit und Handbuch am Ende gar nicht so stark voneinander 😉

Much like a scholarly essay on literature, almost no one will read it, except a select handful of people whom you will never meet.

Kreativ versus standardisiert

Das Schreiben selbst ist für mich in meinem jetzigen Job zwar schon herausfordernd, aber es ist eben auch notwendig standardisiert zu schreiben. Und das ist nicht kreativ! Wer also technischer Redakteur werden will, weil er supergerne schreibt, muss sich darüber im Klaren sein, dass das Schreiben nicht den Hauptteil der Arbeit ausmacht und man dann auch meistens in der Wortwahl und dem Stil sehr eingeschränkt ist. Wer schreiberische Freiheit will, sollte Journalist oder Werber werden. Oder anfangen zu bloggen 😉 Oder nebenbei daheim den langjährigen Roman fertigstellen 😉

Das Kreative liegt für mich in der Art wie ich den Wust an Information, den ich mir zu einem Thema/Produkt aneigne, aufbereite und in eine passende Struktur bringe. Womit wir auch wieder bei den Grundlagen wären, die man aus einem literatur- bzw. sprachwissenschaftlichem Studium mitbringt. Nicht umsonst trifft man in diesem Berufszweig so viele Germanisten, Übersetzer, Romanisten etc.pp.

Das Problem mit der Strukturierung, das ich unlängst hatte, ist tatsächlich nicht so einfach zu lösen. Kurzzusammenfassung: Es ging darum zwei Unterkapitel in einem Oberkapitel zusammenzufassen, das selbst aber eigentlich keinen Inhalt enthält.

title-only topics

Es gibt einerseits den Ansatz  sog. title-only Topics zu benutzen, die lediglich den Titel und eine short description enthalten. Damit kann man dann die gewünschten „leeren“ Oberkapitel erzeugen. Einige argumentieren hier, dass man so eine <shortdesc> auslesen kann, um sie bei Bedarf anzuzeigen, z.B in einer Online-Hilfe. Das ist für mich schon ein smartes Argument, das dem Nutzer hier und da nützen kann. Ein Topichead hat eben keine Beschreibung.

Keine unnötigen Topic-Hülsen!

Jedoch wiegt es für mich schwerer, was für ein Wirrwarr dann auf Erstellerseite entsteht. Ein Topic mit nur einem Titel als Inhalt ist für mich kein Topic, da es kein abgeschlossenes Thema beschreibt o.ä. Punktum! Wenn man mit title-only Topics auch nur anfängt landet ganz man schnell in einem Haufen eigentlich inhaltsleerer Topics und das sollte man meiner Meinung nach tunlichst vermeiden.

Keine Oberkapitel mehr?

Andere Stimmen sagen, dass man einfach davon wegkommen sollte, solche „leeren“ Oberkapitel überhaupt zu benutzen. Aber gerade in klassischen Handbüchern finde ich das irgendwie kaum machbar, ohne dass der Nutzer leidet (wer sich für eine längere Diskussion interessiert, bitte hier lang zur YahooGroup).

Kurzum

Ich habe immer noch keine Lösung. Ich kann aktuell nur hoffen, dass das <topichead>-Verhalten in einer der nächsten OT-Versionen geändert wird. Aktuell fungiert ein <topichead> eben einfach nur als Zwischenüberschrift, jedoch ohne Link, sowohl im PDF als auch im HTML. Oder ich mach’s halt selber 🙁

Hatte ich bei diesem Usability-Vortrag noch gehört, dass User oft Dinge wollen, von denen sie selbst nichts wissen, stolpere ich doch heute glatt über einen uralten Artikel bei Jacob Nielsen: First Rule of Usability? Don’t Listen to Users

Feedback vom User ist wohl so ziemlich für alle Redakteure schwarzes Loch. Was wollen die eigentlich? Wie finden die das, was ich schreibe?

Nur, wie bekommt man dieses Feedback? Eine der Standardantworten ist immer: Umfragen. Wer allerdings schon einmal versucht hat, eine Umfrage aufzusetzen, weiß, dass man sehr viele konzeptionelle Arbeit hineinstecken muss. Gibt man dem User zu viel in der Fragestellung vor oder zu wenig? Versteht er, was nun genau damit gemeint ist? Was ist das Ziel dieser Frage? Lenke ich den User damit schon in das, was ich eigentlich hören will?

Dabei ist dann auch noch wichtig, sich damit zu beschäftigen, wann man das Feedback einholen will.

Finally, you must consider how and when to solicit feedback. Although it might be tempting to simply post a survey online, you’re unlikely to get reliable input (if you get any at all). Users who see the survey and fill it out before they’ve used the site will offer irrelevant answers. Users who see the survey after they’ve used the site will most likely leave without answering the questions.

Bei Hilfetexten ist es für mich klar, dass ich nur Feedback einholen möchte nachdem ein User die Hilfe genutzt hat. Das Spannende dabei ist, wie man den User dann noch abholen kann, da die meisten ja recht fix von der Hilfe verschwinden, wenn sie ihnen was gebracht hat und die meisten auch nicht sehr motiviert sind Feedback zu geben.