Vor einigen Tagen ist mir wieder die große Schwäche in der agilen Softwareentwicklung bewusst geworden: die fehlende, veraltete oder falsche Dokumentation. Ich habe schon erlebt, dass in einem Projekt per Grundsatzentscheidung festgelegt wurde, dass nicht dokumentiert wird (da Dokumentation sowieso immer veraltet ist).
Das agile Manifest sagt, das funktionierende Software höher zu bewerten ist als umfassende Dokumentation. Der Knackpunkt für mich ist das Stichwort "umfassend": Funktionierende Software ist wichtiger als umfassende Dokumentation, umgekehrt ist ein gewisses Maß an Dokumentation unabdingbar für langfristig funktionierende Software.
Eines der zwölf Prinzipien agiler Entwicklung sagt "Die effizienteste und effektivste Methode, Informationen an und innerhalb eines Entwicklungsteams zu übermitteln, ist im Gespräch von Angesicht zu Angesicht". Dem stimme ich zu, aber auch hier muss man sich der Realität stellen:
- Nicht jeder kann in allen Meetings teilnehmen
- In Unternehmen gibt es immer Fluktuation, Wissensträger können verschwinden
- Menschen vergessen manchmal Dinge
- Bei mündlicher Informationsvermittlung kommt es zum "Stille-Post-Phänomen"
Dokumentieren macht den wenigsten Spaß, und es braucht viel Disziplin, um im agilen Prozess die Dokumentation kontinuierlich mit zu pflegen. Deshalb (und so verstehe ich das agile Manifest) ist es sinnvoll, sich beim Dokumentieren auf das Wesentliche zu beschränken:
- Entscheidungen Ein häufiger, schwerer Fehler beim Dokumentieren ist das Auslassen der Entscheidungen. Oft wird nur das "wie" beschrieben, aber nicht das "warum". Dabei ist die Begründung einer Entscheidung viel wichtiger als das Ergebnis, welches sich im Code widerspiegelt. Die Gründe für oder gegen eine bestimmte Architektur, oder eine bestimmte Datenbank sind verloren, wenn sie nicht dokumentiert werden. Im Zeitverlauf kommt es dann zu einem jedem bekannten Problem: Niemand traut sich, Code zu ändern, weil man nicht weiß, ob es irgendwann mal einen "guten Grund" für die aktuelle seltsame Implementierung gab.
- Schnittstellen Schnittstellen sind Grenzen zu anderen Systemen, sei es interne Module, oder externe Schnittstellen zu anderen Systemen. Die Dokumentation von Schnittstelle (einschließlich verwendetem Datenmodell und Migrationsprozess bei Änderungen) ist wichtig, weil oft Teamgrenzen überschritten werden und eine verbindliche und stabile Referenz notwendig ist, um getrennt voneinander entwickeln zu können.
Starre Dokumentationsvorgaben sind in der Regel kontraproduktiv. Womit ich gute Erfahrungen gemacht habe, ist Arc42 einem Template für Architekturdokumentation. Die empfohlene Struktur hilft, nichts wesentliches zu vergessen. Es macht keinen Sinn, das Template auf einen Streich auszufüllen, besser ist es, die Dokumentation im agilen Prozess kontinuierlich zu pflegen; Lücken sind erlaubt. Die Dokumentation pflege ich am liebsten als Markdown-Dokument direkt im jeweiligen Projektrepository. So ist sie immer auffindbar, und paralleles Bearbeiten, z.B. auf unterschiedlichen branches, ist durch einfaches mergen problemlos möglich.
Oft gibt es grundlegende, übergreifende Themen, die nicht in die Dokumentation eines bestimmten Projekts passen. Hier finde ich eine Sammlung von Dokumentationstexten, z.B. in Form von RFCs sehr angenehm. Ob man das in einem Git-Repository verwaltet oder lieber im Wiki ist Geschmacksfrage.
Lange Rede, kurzer Sinn: Dokumentieren ist langweilig und schwer, aber notwendig! Konzentriert euch dabei auf das wesentliche: Entscheidungen und Schnittstellen.