Dokumentation in einer agilen Welt

Dokumentation, ein Begriff der in der Softwareentwicklung fast täglich in den Mund genommen wird. Trotz seiner enormen Präsenz und Wichtigkeit wird sie doch gerne auf die lange Bank geschoben und vernachlässigt. Dennoch ist sie ein enorm wichtiger Bestandteil, eine textuelle Dokumentation der Gegebenheiten und Verhalten eines Systems.

Sei es zu Bedienung, Systemüberblick oder Entscheidungen die in Richtung Architektur gehen. Gerade im agilen Umfeld wird immer wieder die Aussage getätigt "das brauchen wir nicht" oder "das ist zu viel Arbeit". Meine liebste Ausrede ist hierbei "wir sind agil, da ändert sich so schnell alles da macht eine Dokumentation keinen Sinn".

Warum es gerade in diesem Bereich wichtig ist

Doch warum ist Dokumentation gerade im agilen Umfeld wichtig? Eben weil sich eben Dinge schnell ändern können und nicht jede Person an jeder Feinheit oder Änderung beteiligt wird bzw. werden kann. Gerade wenn man massiv skaliert und neue Devs ins Team kommen wird es oft schwierig sich einzufinden.

Techniken

Vorgehen die einem helfen gibt es hierbei zu genüge. Im Folgenden will ich etwas genauer darauf eingehen, was man mit bewährten Konzepten in welchen Bereichen umsetzen kann.

Architecture Decission Record(s)

Abgekürzt ADR bietet eine komfortable Möglichkeit Architekturentscheidungen schnell und präzise zu dokumentieren.

Hierbei geht es nicht darum alles akribisch bis ins kleinste Detail zu dokumentieren, sondern Entscheidungen schlicht und ergreifend aufzuschreiben. Doch was ist anders als bei einer klassischen Systemarchitektur?

Hier wird ganz klar aufgeschlüsselt - wir haben ein Problem und brauchen dafür eine Lösung. Hierbei listet man kurz alle Möglichkeiten auf, wägt ab und entscheidet sich dann auf Basis der Vor- und Nachteile. Ich habe damit schon sehr gute praktische Erfahrungen gemacht und kann das nur empfehlen! Hierbei ist der Vorteil nicht nur, dass man die Entscheidung für neue Team-Member verständlich macht. Auch man selbst kann nochmal nachlesen, warum man sich in der Vergangenheit für einen bestimmten Weg entschieden hat.

Gerade wenn festgestellt wird, dass der falsche Weg gegangen wird, kann man noch einmal zurückspringen und sich die Alternativen ansehen. Häufig scheint dann eine Alternative plötzlich die bessere Wahl. Da man diese schon grundlegend analysiert hat, kann man hier noch einmal auffrischen und hat so unter Umständen in wenigen Minuten einen neuen Weg bereit.

Doch auch andere Projekte können davon profitieren. Gerade im agilen Umfeld mit autarken Teams kann so ein Team ohne große Kommunikation beim anderen Teams "spicken" und hier evtl. sogar Entscheidungen übernehmen oder auf Basis der Vor- und Nachteile eigene Schlüsse ziehen.

Das Format ist sehr leichtgewichtig und für den gestressten Developer, Solution Architect oder DevOps lässt sich das relativ einfach in ein (Git-)Repository integrieren. Bewährt hat sich hier ein Ordner adr der vorzugsweise innerhalb des doc-Folder des Projekt angelegt wird. So hat man schnell eine konsistente Struktur, die man auch über verschiedene Projekte vereinheitlichen kann. Das Format ist hierbei Markdown das alle gängigen Git-Hosting-Tools als HTML visuell ansprechend darstellen können. Natürlich geht das auch gut auf der Konsole, für die Hardcore-Fans ;)

Direkt im Code

Gerade wenn eine Entscheidung den Programmablauf betrifft lohnt es sich die Dokumentation direkt dahin zu verlagern wo man sie erwarten würde, beim Code. Das erspart den Kontext-Wechsel zwischen Dokumentation und Quelltext. Das klappt aber nicht nur bei klassischer Programm-Logik für Business-Software, sondern auch bei Infrastructure as Code.

Ein kleiner Kommentar, wenige Sätze können wichtige Fragen und Unklarheiten klären bzw. gleich vermeiden. Natürlich handelt es sich hier um nichts Neues und sollte selbstverständlich sein in unserer Branche. Jeder der etwas länger im Geschäft ist, wird mir aber zustimmen, dass dies nur sehr selten der Fall ist. Gerade wenn man schnell Anpassungen fährt ist das eine zeit-effiziente Variante.

Hierbei muss ganz klar erwähnt werden das der Kommentar nicht 1:1 die Logik in Textform wiederholen sollte, so kann z. B. folgendes Code-Snippet relevant sein:

// Documents that are older than the maximal storage duration are moved
// to a long time storage archive, we cant delete the document in this
// special case because of a special requirement from the legal department
if(doc.age > MAX_STORAGE_DURATION) {
	doc.moveToLongTimeStore()
}

So stellt sich bei dieser Logik dem Leser nicht die Frage, wieso die Dokumente nach der maximalen Speicherdauer nicht gelöscht werden. Gerade in diesem Fall wäre das für ein langjähriges Team-Member selbstverständlich. Für einen "Projekt-Newbie" stellt sich doch die Frage wieso das Dokument nicht einfach gelöscht wird. Durch den qualifizierten Kommentar erledigt sich das Thema so schon frühzeitig.

Versionsverwaltung

Tools wie Git oder SVN nutzen nicht ohne Grund Commit-Messages. Man commited schließlich nicht seine Änderungen, damit andere sie "stupide" herunterladen können. Auch der Push um der CI/CD willen macht wenig bis gar keinen Sinn.

Ein guter Commit beschreibt den Inhalt der Änderungen, hierbei kann ich nur immer wieder betonen lieber kleine Commits mit übersichtlichem Change-Set als einen "all-in-one". "Refactor some stuff" oder "Add documentation" helfen hierbei wenig bis gar nicht weiter. Wenn das Change-Set sich dann über 300 Dateien erstreckt war es das dann auch schon mit der Nachvollziehbarkeit.

Natürlich sollte man es nicht übertreiben mit den Commits:

Gerade wenn erst die Formatierung angepasst werden muss, lohnt es sich einen separaten Commit zu erstellen wie etwa "chore: Reformat source files for module a". Gute Guidelines, die ich absolut empfehlen kann finden sich auch unter conventionalcommits.org.

Hervorragend ist es die Commits so zu gestalten, dass auf den ersten Blick klar wird was der Commit ändert. Wenn ein Ticket vorliegt kann die Nummer in der Nachricht genutzt werden z. B. docs(TICKET-123): Add ADR for database system. So kann beim Überfliegen der Historie schnell erkannt werden worauf sich die Änderungen beziehen.

Es gibt Fälle in denen sich nicht alles in eine kompakte Nachricht quetschen lässt oder man noch mehr Informationen hinterlassen werden sollen. Ein Feature, das hierbei wenige benutzen sind die Descriptions in Commits. Diese folgen nach einer Leerzeile nach der Commit-Message:

feat(SALES-123): Add sales report for DACH region

Add new sales report for DACH that use the new reporting format with Tool 1.2.

Currently the reports use an old index that might become slow in the future and should be replaced. A separate ticket for this has already been created for the database team (DATABASE-666)

Während das Beispiel vielleicht etwas zu detailliert erscheint macht es dennoch Sinn. Gehen wir davon aus das Repository gehört zu einem cross-funktionalen Team, bei dem auch mal der Frontend-Dev Änderungen macht oder Dinge prüfen muss, weil gerade keine anderen Ressourcen zur Verfügung stehen. Der kennt sich natürlich relativ wenig mit Reports aus und sieht zuerst in der Versionsverwaltung nach. Nehmen wir an, wir nutzen GitHub, ein Product Owner benötigt dringend die Information für Stakeholder, warum der Bericht so langsam lädt. Der Entwickler öffnet also das Repository und sichtet die letzten Commits und sieht "das ist der Commit für den neuen Report", klickt auf die drei Punkte um die Nachricht anzuzeigen und kann sofort feststellen das hier noch Anpassungen für die Performance fehlen. Er schickt also die Information "da fehlen noch Anpassungen an der Datenbank, wenn das Ticket DATABASE-666 fertig ist dann wird der Bericht schneller laufen" an den Product Owner.

Im Idealfall dauert das keine 10 Minuten und schon kann das Team eine fundierte Aussage an die Stakeholder geben. Wäre die Message nicht mit den Details versehen worden, müsste man erst herumfragen. Das dauert dann im schlimmsten Fall mehrere Tage. Diese oder eine ähnlich Situation ist wahrscheinlich sehr vielen ITlern bekannt.

Das schreiben solcher Meta-Informationen kostet nur wenig Zeit und bringt einen riesigen Mehrwert. Wenn man sich etwas dazu zwingt saubere Nachrichten zu verfassen. Dann kommt man hier auch schnell in eine Routine, in der so etwas schnell heruntergetippt ist und immer weniger Zeit erfordert.

Kommunikation mit Team-Mitgliedern

Natürlich ist die Doku wichtig, aber es schadet nicht bei wichtigen Änderungen kurz das Chat-Tool zu öffnen. Kurz in die Dev-Runde oder den internen Team-Chat ein paar Zeilen zu schreiben. Dabei reicht hier schon ein simples "Hey Leute, ich hab in System X das Datenbanksystem umgestellt, wen es interessiert ein ADR liegt im Repository".

Natürlich sehen es die anderen Backend-Entwickler auch wenn sie das Projekt auschecken oder sind im Daily informiert werden. Erfahrungsgemäß geht diese Information trotzdem sehr gerne unter. Also schadet eine kurze Auffrischung nicht.

Welches Maß hier das richtige ist, liegt natürlich sehr stark am Team in dem man arbeitet und auch nach Relevanz der Nachricht. Waren bei der Entscheidung sowieso alle mitarbeitenden Personen beteiligt, dann ist das ziemlich überflüssig.

Hierbei lohnt es sich auf Menschenverstand zu setzen, den man ja sowieso an den Tag legen sollte. Solche Dinge lohnen sich auch in einem Code of Conduct festzuhalten.

Ein Appell zum Schluss

Dokumentation ist ein extrem wichtiges, nerviges und gehasstes Thema zu gleich. Jeder beschwert sich über fehlende oder schlechte Dokumentation. Wenn jedoch die Arbeit nicht aufgeschoben wird, gerade im agilen Umfeld "on demand" dokumentiert wird, dann ist der Zeitaufwand immer relativ gering. Am Besten gewöhnst du dir an die Techniken oberhalb in deinen Workflow zu integrieren.

Du wirst feststellen, dass es sich lohnt und es absolut effektiv ist! In Summe verbringst du dann deutlich weniger Zeit mit Dokumentation oder der Suche danach. Auch wenn du vielleicht der Einzige im Team bist, der das am Anfang umsetzt, kannst du der Vorreiter sein und das Ganze vorantreiben. Letztlich werden deine Kollegen sehen, dass es sich lohnt und es dir gleich tun.

Hast du noch andere Tipps und Techniken? - Hinterlasse gerne einen Kommentar oder schreib mir per Mail/Twitter! Auch über Feedback freue ich mich immer sehr.