Was nur einer weiß, macht das System dümmer

Meistens ist jede:r von uns schon mit Markdown in Berührung gekommen. Wer Markdown nicht kennt: Faule Entwickler:innen haben sich gedacht: "Wie können wir dokumentieren, ohne Word zu öffnen". Daraus ist eine einfache Syntax entstanden die interpretiert und dann wunderschön (im Auge des Betrachters) dargestellt wurde.

Die konsequente Weiterentwicklung von Markdown ist nun Asciidoc. Auch hier geht es darum mit einer einfachen Syntax eine wunderschöne Dokumentation zu erstellen. Die Opensource-Community hat dafür gesorgt, dass Dokumente mit dieser Syntax einfach in PDF, Word, HTML (Antora), Confluence (Confluence-Publisher), uvm. konvertiert werden können.

Mit Asciidoc war es nun ein Einfaches, Dokumentation zu schreiben die im Confluence veröffentlicht und somit kein neues Tool benötigt wird. Nun ist der Weg geebnet, dass die Dokumentation für jeden zugänglich ist.

Gute Dokumentation zu Asciidoc findet ihr hier:

Da wir nun unsere Dokumentation wie Code behandeln, gewinnen wir dadurch auch wertvolle Features:

Gerade der letzte Punkt ist ein Gamechanger. Denn wie oft haben wir schon Dokumentation gelesen die veraltet war? Frei nach dem Motto: "Geschrieben Dokumentation ist am nächsten Tag wieder veraltet". Wenn das Entwickler:innenteam die DoD einhält, entwickelt sich die Dokumentation parallel zum Code mit. Ergo: Keine veraltete Dokumentation mehr. Bei Opensource Projekten werden Pull-Request mit fehlender Dokumentation gnadenlos abgelehnt. Also warum nicht ein Vorgehen implementieren, dass sich bereits bewährt hat? Abgesehen von SHWESIG (So Haben Wir Es Schon Immer Gemacht)

Somit muss ein Pull-Request neben Code & Unit-Tests nun auch Dokumentation beinhalten.

Heißt das jetzt, jeder muss seitenweise Dokumentation schreiben? Ist dies nicht das Gegenteil von Agilität? Agilität heißt auch, dass in crossfunktionalen Teams (theoretisch) jeder die Aufgabe des anderen Übernehmen könnte. Daher muss täglich so viel Wissen vermittelt werden, dass ich Morgen vom Bus überfahren werden könnte und dennoch das Team weiter die anstehenden Aufgaben, ohne mich, erledigen könnte (natürlich trauriger). So viel Wissensvermittlung am Tag kann nur stattfinden, wenn wir Pair- oder Mob-Programming praktizieren. Die Alternative ist die Dokumentation.

Daher solltet ihr so wenig wie möglich und so viel wie nötig Dokumentation generieren. Was genau dies bedeutet, unterscheidet sich je nach Projektkontext. Dies sollte im Team abgestimmt werden.

Was ist nun besser als Theorie? Natürlich die Praxis. Daher möchte ich euch einige Beispiele aus der Opensource-Welt mitgeben, die zeigen wie gut das Dokumentieren mit Asciidoc in der Praxis funktioniert:

Und dies sind jetzt nur mir bekannte Beispiele mit Asciidoc. Es gibt noch weitere mit Markdown die mit dem Tool Jekyll ihre Dokumentation erzeugen. Am Ende ist es nicht relevant, ob ihr Markdown oder Asciidoc verwendet, Hauptsache die Dokumentation liegt nahe am Code und kann wie Code behandelt werden.

Da wir nun zu jedem neuen Feature Dokumentation erzeugen oder Anpassen, diese im Pull-Request pair-reviewed und in einer CI-Pipeline mit z.B. dem Confluence-Publisher erzeugt und veröffentlicht wird, steht der "Continuous Documentation" nichts mehr im Wege. Naja außer dem Projekt-druck, dass schnelle Fixen von Bugs, SHWESIG - daher brauchen wir es nicht, usw. Es liegt an uns, ob wir Dokumentation zum Teil unseres Entwicklungsprozesses (und zur Gewohnheit) machen. Dadurch unser Wissen teilen und das System/unser Team/unsere Firma stärken oder ob wir weiterhin Wissens-Silos aufbauen und damit dieses System dümmer machen.

Dokumentation kann eine Chance sein, Wissen zu verteilen und damit das Team/die Firma zu stärken. Somit kann sich schnell in Code und Module eingearbeitet werden ohne anstrengende Analysen. So ist es einfacher uns gegenseitig zu Unterstützen und unseren Alltag zu verbessern, denn was einer alleine nicht schafft, das schaffen viele.