© alphaspirit, 123RF

Verteilte Teams, die Software professionell dokumentieren, brauchen keine simultan arbeitenden Multiuser-Editoren, sondern robuste Workflows, ein ausgeklügeltes Projektmanagement und Git – weiß der Autor des Beitrages, der die Dokumentationsabteilung eines großen Distributionsherstellers leitet.

Die externen Autoren nicht mit eingerechnet umfasst das Dokumentationsteam bei meinem Arbeitgeber Suse derzeit 15 Mitarbeiter, Tendenz steigend. Die Arbeitsplätze der Mitglieder sind in Nürnberg, Prag, Berlin und Washington State, also verteilt auf zwei Kontinente. Dass dies beim Erledigen unserer gemeinsamen Aufgabe, nämlich die Software und Dienste des Suse-Produktportfolios zu dokumentieren, kein Hindernis bedeutet, hatte Douglas Engelbart vom Stanford Research Institute bereits am 9. Dezember 1968 in seiner legendären “Mother of All Demos”-Präsentation [1] vorausgesagt (Abbildung 1).

Abbildung 1: In der Mutter aller IT-Demos, “Engelbart and the Dawn of Interactive Computing”, skizzierte der Stanford-Vordenker bereits 1968 neben der ersten Computermaus auch das kollaborativen Editieren.

In der (schwarz-weiß überlieferten) 90-Minuten-Vorführung schilderte und demonstrierte der promovierte Visionär den Arbeitsplatz der Zukunft, das Arbeiten mit Fenstern, Hypertext, einem Videokonferenzsystem und einer Art Maus. Ein Jahr vor dem ersten Mondflug und 37 Jahre vor Google Text & Tabellen zeigte Engelbart dynamisches Linken, Revisionskontrolle und einen Editor, den mehrere Benutzer zeitgleich bedienen.

Sprung ins Heute

Ende 2017 liefert der Suchbegriff “Collaborative Editing” bei Google annähernd 100 Millionen Treffer. Softwarehersteller wie Atlassian, Google, Open Xchange, Owncloud, WordPress oder Microsoft wollen auf den Google-Ergebnisseiten wie auch auf dem Markt gerne als die Nummer 1 auftauchen.

Nicht jeder Hersteller kann Echtzeitkollaboration bieten: Libre Office Online [2] ist nach Aussage der Entwickler noch nicht soweit, integriert sich aber in Nextcloud. OX Documents [3] aus dem Hause Open Xchange wie auch Google Documents machen einen ausgereifteren Eindruck. Wie auch Microsoft erlauben es die beiden Anbieter mehreren Nutzern, gleichzeitig und sichtbar am selben Dokument zu arbeiten (siehe auch “Bitparade” in diesem Schwerpunkt).

In der Praxis spielt sich das gemeinsame Bearbeiten von Texten und Quellcode allerdings mehrheitlich in Browserfenstern ab. Etherpad [4], das als Urahn der Gattung wahrgenommen wird, stammt aus dem Jahr 2008 und sorgte nach einem Slashdot-Bericht gleich am dritten Tag seiner Existenz für Aufsehen, als die Demoserver vor Überlast in die Knie gingen. Die drei Hauptentwickler David Greenspan, Aaron Iba und J.D. Zamfirescu publizierten ein knappes Jahr später einen Vergleich zwischen Etherpad und Google Wave, der dazu führte, dass der Suchmaschinenriese die Software aufkaufte, den Quelltext freigab und Etherpad in Google Wave integrierte.

Wegen Lizenzproblemen und weil Teile des Originals in Scala geschrieben waren, entstanden in der Folge diverse Klone wie Firepad [5], allen voran aber Etherpad Lite (Abbildung 2, [6]). Firepad hat sich seinen Weg in mehrere Produkte gebrannt, etwa ins Atlassian-Wiki oder in den Markdown-Editor Socrates.

Abbildung 2: Etherpad Lite verwendet Javascript auf der Serverseite (in Node.js), bietet ein HTTP-API, ein Jquery-Plugin und jede Menge Clients in diversen Programmiersprachen.

Collaborative Editing – oder nicht?

Die Tools eignen sich prima, um gemeinsam Konzepte zu programmieren, Ideen zu ordnen, fürs Brainstorming, zum Protokollieren eines Meetings oder um Material für die Marketingabteilung vorzubereiten (siehe andere Schwerpunkt-Artikel). Für professionelle Dokumentation taugen sie aber kaum: Der Funktionsumfang ist im Vergleich zu nativen Programmen arg eingeschränkt, es fehlt an etlichen Formatierungen, Makros oder Variablen – ganz zu schweigen davon, was nach dem Export übrig bleibt.

Hinzu kommen das Traffic-Gewitter, das jeder auslöst, der viel Text aus seiner Zwischenablage in den Editor wirft. Zugleich reagieren diese Tools unbarmherzig auf versehentliche Eingaben, zu denen auch eingefügte eigene Passwörter zählen, die man so nicht nur herausposaunt, sondern auch in der History verewigt.

Das erklärt auch, warum derlei Tools zwar bei agilen Entwicklern im Zuge des Pair Programming oder beim Realtime Collaborative Editing Zug um Zug an Boden gewinnen, auf Dokumentationskonferenzen wie der “Write The Docs” [7] aber kaum sichtbar sind. Allenfalls arbeiten kleine Projekte gemeinsam mit Tools wie Screen [8] oder Wemux [9] an einer Datei. Die meisten Editoren sind aber nicht dafür ausgelegt und brauchen Add-ons wie etwa Vim [10] oder Emacs [11].

Der Praxis-Check

Wer wie meine Kollegen professionelle IT-Dokumentation schreibt, beispielsweise für längere Handbücher, landet gewöhnlich bei Sprachen wie Asciidoc oder Docbook XML. (Der Funktionsumfang der gängigen Markdown-Dialekte genügt leider nicht.) Bei Suse setzen wir auch deshalb auf XML, weil es Entities – eine Art flexibler Makros und Variablen – und Funktionen bietet, die das Team für die Handbücher benötigt. Jeder Autor bestimmt dabei frei, welchen Editor er für seine Quelltexte – Ja, auch Dokumentation hat Quelltexte! – verwendet.

Das vom Kollegen Frank Sundermeyer gepflegte Single-Source-Publishing-Werkzeug Daps [12] sorgt dann dafür, dass Absätze nur im Handbuch der Produkte auftauchen, wenn der Autor sie dafür getaggt hat. Die Produktnamen stehen in einer separaten Entity-Datei. Mit Hilfe von Docbook Profiling wählt die Software automatisch passend zu jedem Produkt die richtigen Namen. Stylechecker korrigieren Schreibweisen und unerwünschte Ausdrucksformen.

Ein separates Tool, der Docmanager, taggt Docbook-XML-Dateien mit einem Bearbeitungsstatus, dem »Besitzer« und Attributen wie »Übersetzung Ja/Nein«. Auch ein Reporting ist enthalten: Die Attribute kann sich ein Projektleiter in Listen anzeigen lassen, einschließlich des Bearbeitungsfortschritts. Am Ende sind es diese Funktionen, die der Dokumentationsprofi wirklich braucht.

Der Workflow

Meine Teamkollegen und ich kommunzieren zu 99 Prozent über Mail, IRC und für Meetings per Videokonferenz. Neben einer Open-Source-Toolchain mit Daps, Docmanager sowie den Stylecheckern – die erzwingen wie erwähnt den Suse-Dokumentations-Stil mit korrekten Produktnamen und Schreibweisen – spielt das Versionskontrollsystem Git für den Workflow eine tragende Rolle.

Seit 2015 verwendet das Team nämlich das vom niederländischen Software-Ingenieur Vincent Driessen entworfene Gitflow-Branching-Modell ([13], Abbildung 3) mit Feature- und Development Branches. Das ermöglicht es Entwicklern, mit anderen zu kollaborieren, bevor das eigene Ergebnis in der Hauptlinie (Master) landet. Driessens Workflow hat sich bei uns wirklich bewährt und als viel essenzieller erwiesen als jede Abwägung zwischen diesem oder jenem Editor.

Abbildung 3: Vincent Driessens Gitflow-Branching-Modell ist zwar für Programmierer gemacht, hat sich aber auch bei der gemeinsamen Arbeit an großen Dokumentations-Projekten bewährt.

Nehmen doch einmal zwei Mitarbeiter gleichzeitig Änderungen an einer Datei vor, kann Git den daraus resultierenden Konflikt automatisch auflösen – außer die Konkurrenzsituation betrifft dieselbe Zeile, was in der Praxis äußerst selten auftritt. Andernfalls gibt Git dem Benutzer, der das »git merge«-Kommando aufruft, einen Fehler aus und präsentiert eine einem Diff ähnelnde Ansicht mit den Changes. E-Mails informieren andere Nutzer über Änderungen.

Driessens Modell adressiert eher Programmierer als Dokumentationsexperten und geht daher mit seinen Feature-und Develop-Branches deutlich weiter als das fürs Doku-Teams notwendig wäre. Zusätzlich lassen sich über Release- oder Maintenance-Branches neue Snapshots erzeugen, die Anwender jederzeit als Tarball aus Github herunterladen. Sein Modell beinhaltet auch Lösungen für schnelle Korrekturen mit hoher Priorität (Hotfix Branches) – was es dem Team ermöglicht, weiterzuarbeiten, während andere wichtige Patches einspielen, die später die Grundlage der nächsten Softwareversion werden.

Verfassen nach Maß

Werkzeuge, die fürs Collaborative Editing erschaffen wurden, eignen sich sehr gut für kurze Texte, die zum Beispiel mehrere Projektmitarbeiter vorbereitend oder im Anschluss an ein Meeting bearbeiten. In die Welt des professionellen Dokumentierens dringt das Konzept aus guten Gründen selten vor. Denn hier kommt es auf geschickte Projektsteuerung und Dateiformate an. An Git beispielsweise führt für viele kein Weg vorbei. (jk)