Zum Wochenende: Dokumentation von Projekten

Eigentlich wollte ich diesen Text Dokumentation von Code nennen, mir ist aber beim Schreiben aufgefallen, dass dieses Thema viel grösser ist.

Mich wurmt das Thema Dokumentation schon seit meines Studiums. Wir haben viel von Projektorganisationstechniken, wie Agile, Wasserfall oder V-Modell gelernt. Wir haben DevOps in einer Tiefe besprochen, dass es einem schon wieder an den Ohren auslief. Aber das Thema Dokumentation wurde immer nur sehr holzschnittartig betrachtet.

Jedes Mal, wenn es zur Sprache kam, wurde nur auf Softwaresysteme, wie JavaDoc, Doxygen und PHPdoc verwiesen. Damit dokumentiert man Code. Nicht zu viel, damit nicht bei jeder Änderung die Dokumentation angepasst werden muss und nicht zu wenig, sodass es praktisch nutzlos für das Verständnis wird. Für den „Rest“ gibt es UML, einen Standard der sehr präzise ist, aber derartig wenig Freiraum lässt, dass ich praktisch niemanden kenne, der ihn Standardkonform verwendet. Klassendiagramme sind dabei mein Lieblingskonstrukt, sie werden sehr schnell unübersichtlich ab einer gewissen Projektgröße, sodass man sich durch verschiedene Ebenen der Abstraktion bewegt, man aber ohne wochenlange Einarbeitung an der geistigen Speicherkapazität scheitert, wenn man in der dritten Ebene angekommen ist und nicht mehr weiß, was man ursprünglich suchte.

Ein Drama in mehr als 40 Wörtern.

Daneben gibt es die Puristen, sie predigen mir, dass der Code schon eine Dokumentation ist. Nun, sie haben im gewissen Sinne recht. Code stellt eine Arbeitsanweisung in einer Sprache dar, die ein Automat verarbeiten kann. Mit genügend Verständnis kann ich dieser Automat sein.

Tja, schön wärs.

Ich bin ein Mensch und keine Maschine. Ich kenne Frustration und wenn ich eins nicht leiden kann, ist es mich durch die in Code kristallisierten Gedanken mir fremder Menschen durchzukämpfen, um zu verstehen, was die Intention (Gedanke) der Autorin war. Stundenlange Lektüre von verschachtelten Ideen, Gedanken und Strukturen ohne jegliche Führung: eine Qual.

So, aber was will ich eigentlich? Ich will die 70er und 80er wieder. Ein Programm braucht einen 1.000 Seiten Wälzer, der mir anhand von Codeauszügen, Diagrammen und Begleittext erklärt, welche Aufgaben wie gelöst wurden. Ich brauche kein Ticket-System, durch das ich mich durchkämpfe, um an das Issue zu kommen, der auf ein Ticket verweist, dass ein Feature implementiert, der den Link auf die halbgare Dokumentation im Wiki enthält. Ich will eine lektorierte Form von Gedanken haben. Eine Struktur des Wissens, eine Struktur, die mich nicht vollkommen erschöpft. Eine Struktur, die das Wissen aus den Köpfen der Autoren befreit. Eine Struktur, die mich nicht an meiner Arbeit verzweifeln lässt.

Als ich die Dokumentation zu BeOS einmal fand, war ich hellauf begeistert. Dort war alles erklärt: die Oberfläche, die Funktionen, die API und die Art und Weise der Zugriffe, mit Beispielen und Auszügen.

Aber das reicht heutzutage nicht mehr. Heute ist alles in Projekten organisiert, wir müssen demnach auch die Struktur des Projekts in der Dokumentation abbilden. Aber bitte nicht in Wikis oder Ticket-Systemen, niemand hält dort die Ordnung aufrecht, es endet immer in einer Flut aus Links und verschiedenen Strukturen an Organisation. Besonders furchtbar wird es, wenn das alte System gegen ein Neues ausgetauscht wird, oder Features hinzukommen oder entfernt werden. Die Evolution führt zu Brüchen in der Struktur, etwas, das natürlich auch nicht dokumentiert ist und niemand macht sich die Mühe, die alten Formate auf die neuen zu migrieren. Es heisst dann immer: keine Zeit, Personalmangel.

Deswegen ein Appell an die Projektmanager und Organisationsforscherinnen: Bitte entwerft eine Struktur im Agilen, die einen Verantwortlichen für Dokumentation einführt. Jemand, der mich und meine Kollegen zwingt, unsere Arbeit mit einem hohen Standard zu dokumentieren. Diese zusammenführt, lektoriert und veröffentlicht. Jemand, der uns schult, die Ticket-Systeme historisch einheitlich hält. Der Fremddokumentation bereitstellt und uns anhält diese, um unser Wissen zu erweitern. Jemand, der mir mit einem stolzen Lächeln die 1.000 Seiten Dokumentation überreicht.

Wie meistens, handelt es sich auch bei diesem Beitrag zum Wochenende, um einen Meinungsartikel.