Dokumentation zuerst!

Der klassische Weg, eine Dokumentation zu schreiben, geht ungefähr so: Die Entwickler erstellen ein wunderbares neues Produkt (wir nehmen mal an: eine TYPO3-Extension). Wenn das Produkt fertig ist, geben sie es an eine Art journalistische Abteilung, die dazu die Dokumentation schreiben soll. Diese Abteilung erforscht das Produkt als wäre es ein Fundstück vom Mars und schreibt für die Öffentlichkeit auf, was sie herausgefunden hat.

In einer anderen Variante tritt der Entwickler selbst nach dem Abschluss seiner Arbeiten an und schreibt noch rasch eine Dokumentation. Er findet sich dabei mit überraschenden Schwierigkeiten konfrontiert und beschreibt schließlich das, was ihm selbst am meisten auf dem Herzen liegt: Die trickreiche Konfiguration, die er gefunden hat, das Unterfeature Z auch unter sehr besonderen Randbedingungen zum Laufen zu bringen. 

Beide Ansätze sind mühsam und beide führen dazu, dass die Dokumentation schwer verständlich wird, wesentliche Aspekte nicht abdeckt und den Nutzer an vielen Stellen ratlos zurück lässt. 

Daher werben wir hier für ein gänzlich anderes Herangehen: Dokumentation zuerst!

Ja, wirklich: Die Dokumentation entsteht vor der ersten Zeile Code!

Das ist nicht so abwegig, wie es sich vielleicht anhört, denn jedes Projekt beginnt ja mit Vorüberlegungen. Man sieht ein bestimmtes Problem, überlegt, wie man es lösen könnte, mustert (in unserem Beispiel) die vorhandenen TYPO3-Extensions, findet, dass keine den Ansprüchen genügt, und beschließt, selbst eine Extension zu erstellen. 

Das genau sind Informationen, die einen künftigen Nutzer zu allererst interessieren: Warum gibt es diese Extension? Welche Alternativen existieren? Und welches Problem löst diese Extension, das die anderen nicht lösen?

Solche Informationen ergeben einen perfekten Einleitungsteil für die Extension-Dokumentation. Sie ist hilfreich für den künftigen Nutzer - und noch viel hilfreicher für die Entwickler. Denn das gibt den Rahmen vor, in dem sich die kommende Entwicklungsarbeit abspielt.

Natürlich ist die Dokumentation damit bei weitem nicht beendet. Es ist nur der erste Pflock eingeschlagen: Darum soll es gehen; das ist die Richtung.

Natürlich kann es im Lauf der Entwicklung passieren, dass neue Aspekte sichtbar werden, dass man die Stoßrichtung noch korrigieren muss. Kein Problem: Dann wird die Dokumentation eben angepasst. 

Aber indem die Dokumentation angepasst wird, wird auch allen Beteiligten klar kommuniziert: Hier hat sich unsere Stoßrichtung geändert. Wir gehen jetzt in eine leicht andere Richtung weiter.

Ganz analog geht der folgenden Entwicklungsprozess weiter: Jedes Projekt besteht aus vielen einzelnen Teilen, jeder Teil aus einzelnen Schritten. Vor jedem Teilschritt überlegt man sich natürlicherweise, wie dieser ablaufen soll. 

Diese Überlegungen finden bei kleinen Projekten nur im Kopf des Entwicklers statt (der in Personalunion Entwickler, Redakteur und Test-User ist). Da ist es hilfreich, die Gedanken schriftlich fest zu halten. So hat man stets einen klaren Fahrplan, was als nächstes zu verwirklichen ist. Und wenn man es schon schriftlich fest hält: Warum dann nicht gleich im Dokumentations-Dokument?

Noch viel naheliegender ist das bei größeren Projekten. Hier werden schon in der Planung viele Menschen einbezogen. Sie repräsentieren verschiedene Nutzergruppen, bringen Aspekte der Umsetzbarkeit und der Barrierefreiheit mit ins Spiel, beleuchten Usability-Aspekte. All diese Aspekte werden sowieso in einem immer ausgefeilteren Dokument erörtert.

Da ist es nur noch ein kleiner Schritt, das Ergebnis dieser Erörterung gleich als Bestandteil der Dokumentation auszuführen. 

Auf diese Weise lässt sich eine ganzes neues Projekt jeweils schrittweise verfeinern. Die Dokumentation entsteht dabei parallel zur Entwicklung und ist quasi immer einen halben Schritt voraus.  

Am Ende wird die Dokumentation zusammen mit dem Produkt fertig. Sie wurde vielfach gelesen, ist getestet, war für die Entwickler nützlich und wird es auch für die künftigen Nutzer sein. Und niemand musste zum Schreiben verdonnert werden.

Dass dieser Weg der “natürlichen” Dokumentation der bessere ist, hat auch mit den Eigenheiten menschlicher Kommunikation zu tun. Dokumentation ist Kommunikation. Und Kommunikation muss sich am jeweiligen Empfänger ausrichten. 

Deshalb sind Spezialisten im Normalfall besonders schlechte Kommunikatoren: Sie stecken zu tief in der Materie, ihnen sind alle Anfangsfragen fremd geworden, sie haben das Staunen und das Rätseln längst verloren. 

Das aber ist genau die Position, in der sich ein erster Nutzer einer TYPO3-Extension wieder findet: Er weiß nicht, was er von der Extension erwarten kann und will Antworten darauf in der Dokumentation finden. 

Am dichtesten kommt ein Entwickler diesem Mindset vor dem Beginn seiner eigenen Arbeiten. Dann ist ihm das kommende Produkt noch fremd, er ist noch nicht hineingetaucht, und dann kann er den Bewußtseinsgraben, der ihn vom unbedarften Erst-Nutzer trennt, am ehesten überwinden. 

Wir sind natürlich nicht die ersten, die “Dokumentation zuerst” fordern. 

Es gibt immer wieder Ansätze dazu, so eine lange Diskussion von 2017 von Seth Kenlon auf opensource.com über “doc-driven development”. 

Es gibt sogar einen internationalen Zusammenschluss der Dokumentations-Redakteure unter www.writethedocs.org. Für sie ist es eine Selbstverständlichkeit: “Dokumentation startet vor der Entwicklung”.

Hinzu kommen verwandte Ansätze, die ähnlich sind, aber doch einen etwas anderen Fokus haben. So zum Beispiel BDD: Behavior Driven Development. Es versucht, eine gemeinsame Sprache von Entscheidern und Entwicklern zu finden, endet aber in einem recht formalisierten Rahmen, der noch weit von der natürlichen Sprache der Nutzer entfernt ist, und nicht zu einer natürlichen und gut verständlchen Dokumentation führt. 

Wer aber die Dokumentation wirklich von Anfang an der Umsetzung voraus laufen lässt, wird mit erstaunlichen Einsparungen honoriert. Man vermeidet zeitraubende Missverständnisse, man vermeidet Implementierungen, die nachher schwierig zu bedienen sind, man vermeidet überflüssige Korrekturen.

• Die Arbeit an der Dokumentation muss als gleichwertige Arbeitszeit gelten. Die Entwickler-Leistung darf nicht nur an der Anzahl der Code-Zeilen gemessen werden.
• Zu Beginn sollte ein sinnvolles Dokumentations-Gerüst zur Verfügung stehen, damit man nicht mit einer leeren Seite beginnen muss. 
• Es muss Beispiele geben, an denen man sehen kann, wie ähnliche Dokumentation aufgebaut ist. 
• Die Dokumentation muss an einem zentralen Ort für alle Beteiligten in ihrer jeweils aktuellen Fassung vorzufinden sein. 
• Nachträgliche Änderungen an bereits beschlossenen Teilen der Dokumentation müssen allen Beteiligten aktiv kommuniziert werden (z.B. über Slack o.ä.)
• So früh wie möglich muss man echte externe User einbinden, die nichts mit dem Projekt zu tun haben. Sie bringen den frischen Blick mit und stellen die naiven - die wichtigen - Fragen. 

Wenn Sie ein neues Feature für Ihre TYPO3-Seite benötigen und Ihnen Ihre Redakteure und künftigen Nutzer am Herzen liegen - kontaktieren Sie uns für eine erstklassig dokumentierte Umsetzung.