Als das „Agile Manifest“ im Jahr 2001 den Grundsatz „funktionierende Software vor umfassender Dokumentation“ verkündete, fanden Entwicklungsteams Gefallen an der Idee einer neuen Arbeitsweise.

Eine umfangreiche Dokumentation war zum damaligen Zeitpunkt die Regel, stellte aber auch eine Barriere für effizientes Arbeiten dar. Die Erstellung war zeitaufwändig, es gab wenig Spielraum für Anpassungen und die Dokumentation musste ständig gepflegt werden. Diese einfache Zeile im „Agilen Manifest“ erkannte diese Herausforderungen an, und viele Teams nahmen dies zum Anlass, sich ein für alle Mal von der Dokumentation zu verabschieden.

Allerdings hatten Teams, die komplett auf die Erstellung von Dokumentationen verzichteten, mit einer Reihe anderer Herausforderungen zu kämpfen: Sie hatten Schwierigkeiten, Wissen auszutauschen, Entscheidungen und Fortschritte abzustimmen, neue Teammitglieder einzuarbeiten oder Probleme zu beheben. Mit der Zunahme der Remote-Arbeit haben sich diese Herausforderungen in den letzten Jahren noch verschärft.

Es ist klar, dass Entwicklungsumgebungen, die auf umfassende Dokumentationen setzen, weder effizient noch effektiv sind – aber das Gleiche gilt auch für die komplette Abschaffung der Dokumentation. Das wirft die Frage auf, welche Rolle die Dokumentation in der agilen Entwicklung spielt?

Um eine Antwort auf diese Frage zu finden, haben wir mit James Grenning gesprochen, einem der ursprünglichen Autoren des Agilen Manifests und dem Gründer von Wingman Software. In diesem Interview erklärt James Grenning, was mit dieser häufig falsch interpretierten Zeile aus dem „Agilen Manifest“ wirklich gemeint ist. Er zeigt uns außerdem, wie moderne agile Teams das richtige Maß an Dokumentation finden können, um effizient zu arbeiten.

Werfen wir einen Blick zurück auf die Entstehung des „Agilen Manifests“. Wie kam es zu diesem Projekt? 

James Grenning: Damals arbeitete ich mit Bob Martin zusammen, und er fragte mich, ob ich am Lightweight Methods Summit im Snowbird Ski Resort in Utah teilnehmen möchte. Mit „Lightweight Methods“ (etwa „schlanke Methoden“) waren Konzepte wie Extreme Programming, Feature-Driven Development und Scrum gemeint, die im Vergleich zu den eher prozesslastigen Ansätzen der 80er und 90er Jahre nur minimale Abläufe und Komponenten umfassten. 

Ich war ein Anhänger des Extreme Programming (XP)-Ansatzes, aber es waren auch Fachleute aus allen anderen Lightweight-Software-Disziplinen auf dem Kongress anwesend. Trotz unserer unterschiedlichen Hintergründe hatten wir alle den Wunsch, die Methoden der Softwareentwicklung zu verbessern. Wir wollten allerdings nicht als die „Lightweights“ (Leichtgewichte) bezeichnet werden, also mussten wir einen neuen Namen finden, weshalb wir das Ganze heute „Agile Softwareentwicklung“ nennen.

Es gab viele Diskussionen und unterschiedliche Meinungen, wobei wir uns darauf konzentrierten, die Dinge zu finden, auf die wir uns einigen konnten. Ich bin Ingenieur und hatte eigentlich erwartet, dass wir viel über technische Prozesse sprechen würden. Aber es stellte sich heraus, dass die Menschen und Teamarbeit die wichtigsten Themen waren. Wir formulierten anhand dieser Themen Wertaussagen, die wir nach ihrer Priorität einordneten – betonten aber auch, dass die nicht so stark priorisierten Themen trotzdem für den Entwicklungsprozess wertvoll sind. So entstanden die vier Grundsätze, die Sie heute kennen.

Ich hatte nicht wirklich erwartet, dass sich die Leute dafür interessieren würden, als Ward Cunningham das „Agile Manifest“ zum ersten Mal online stellte. Aber ich wurde eines Besseren belehrt und das Interesse der Leute war da. Ich war zwar überrascht, aber ich denke, es hat gezeigt, wie viele Menschen sich mit den Herausforderungen der Softwareentwicklung auseinandersetzen und sich eine bessere Arbeitsweise wünschen. 

Lassen Sie uns eine der Zeilen aus dem „Agilen Manifest“ genauer unter die Lupe nehmen. Was war die ursprüngliche Absicht hinter der Aussage „funktionierende Software vor umfassender Dokumentation“? 

JG: Die damalige Denkweise war: „Erst dokumentieren, dann entwickeln.“ Aber Dokumentation ist teuer. Sie bietet nicht nur Vorteile, sondern ist auch ein Kostenfaktor.

Ein Ziel der traditionellen Dokumentation war es, die Kundenwünsche schriftlich festzuhalten und im Vorfeld mit der Entwicklung abzustimmen, damit das Team anschließend in Ruhe arbeiten konnte. Bei dieser Herangehensweise gibt es allerdings ein Problem: Wenn Kundinnen und Kunden nur einmal im Jahr Produktwünsche äußern, werden sie alles Mögliche verlangen – aber sie werden ihre Meinung ändern, wenn die Software geliefert wird.

Kent Beck, Ward Cummingham, Ron Jefferies und andere XP-Begeisterte wussten, dass die Erstellung von Dokumentationen auf diese Weise nicht nur zeitaufwändig war, sondern es dem Team auch nicht ermöglichte, neue Erkenntnisse zu berücksichtigen oder auf Änderungen zu reagieren. 

Die Zeile „funktionierende Software vor umfassender Dokumentation“ stand für einen grundlegenden Wandel im Denken rund um die Dokumentation. Dabei wurde vorgeschlagen, dass wir nicht von Anfang an auf eine umfassende Dokumentation setzen, sondern schrittweise während der Entwicklung der Software eine wertvolle Dokumentation erstellen sollten. 

Die Dokumentation scheint heute ein Stigma in der agilen Entwicklung zu sein. Welche Meinung haben Sie zur Rolle der Dokumentation in der agilen Softwareentwicklung? 

JG: Die Formulierungen im „Agilen Manifest“ sagen eigentlich aus, dass eine Sache der anderen gegenüber zu priorisieren ist. Aber sie werden leider fälschlicherweise oft so interpretiert, dass eine Sache getan werden soll, die andere aber nicht. Wir sehen das häufig bei der Dokumentation. 

Wir wollten nicht andeuten, dass Teams keinerlei Dokumentation erstellen sollten. Es gibt einfach kein Patentrezept für die Dokumentation. Das „Agile Manifest“ erwähnt mit keinem Wort, wie man die Dokumentation angehen sollte, denn wir wüssten überhaupt nicht, was wir dazu sagen sollten. Schließlich sind die Bedürfnisse in jedem Team anders. Aber nur weil es keine spezifische Anleitung zur Erstellung einer Dokumentation gibt, heißt das nicht, dass Sie überhaupt keine brauchen. 

Dokumentation kann unglaublich nützlich sein, wenn es darum geht, Teams und Beteiligte auf einen Nenner zu bringen. So ist beispielsweise eine Designdokumentation für die Systemwartung, externe Prüfstellen und externe Entwicklerinnen und Entwickler erforderlich. Entscheidend ist, dass Sie erkennen, dass der Dokumentationsbedarf von Faktoren wie Teamgröße, Verteilung, Vorschriften und Branche abhängt.

Ich würde Teams empfehlen, das „Agile Manifest“ als Ausgangspunkt für Diskussionen zu verwenden, um herauszufinden, welche besonderen Bedürfnisse erfüllt werden müssen. Ein kleines Team, das sich an einem gemeinsamen Ort befindet, kann sich beispielsweise persönlich über ein Whiteboard zu technischen Informationen wie der Architektur austauschen. Aber ein großes Team, das über den ganzen Globus verstreut ist, muss neue Wege finden, um diese Informationen zu kommunizieren. 

Nachdem wir nun wissen, dass es keine vorgeschriebene Formel für die Dokumentation gibt: Welchen Rat würden Sie agilen Teams heute in Bezug auf die Dokumentation geben?

JG: Erstens: Denken Sie daran, dass jedes von Ihnen erstellte Dokument einen Nutzen haben sollte. Bevor Sie sich an die Erstellung einer Dokumentation im Rahmen Ihrer agilen Entwicklung machen, sollten Sie sich darüber im Klaren sein, für wen diese Dokumentation erstellt und wofür sie verwendet wird. Dies hilft, Ressourcenverschwendung zu vermeiden, und spart Zeit, da die richtigen Personen in den Prozess der Dokumenterstellung einbezogen werden. 

Wenn Sie sich entscheiden, ein Dokument zu erstellen, beachten Sie die folgenden Tipps:

Verwenden Sie visuelle Elemente für eine allgemeine Abstimmung 

Visuelle Elemente sind eine großartige Möglichkeit, Ideen zu sammeln und Menschen auf den gleichen Stand zu bringen. Beginnen Sie mit einer klaren Vorstellung davon, wo Sie hinwollen. Stellen Sie sich das Ganze wie bei einer Landkarte vor. Wenn Sie etwas von Grund auf neu entwickeln, sollten Sie mit einem Dokument beginnen, das die Lage der Dinge beschreibt, die Konventionen festlegt und Ihnen und Ihrem Team hilft, das System zu verstehen. 

Am wichtigsten ist jedoch, dass Sie wissen, wann Sie aufhören müssen. Nutzen Sie diese visuellen Elemente, um die Interaktion zwischen den Systemen zu veranschaulichen und sich aufeinander abzustimmen, aber übertreiben Sie es nicht. Es kann Dutzende von ähnlichen Szenarien geben: Dokumentieren Sie einige davon, um das Muster zu verdeutlichen und Beteiligte aufeinander abzustimmen.

Iterative Erstellung von Dokumentationen

Beginnen Sie mit einer Produktvision. Sie ist wahrscheinlich anfangs noch unklar und verschwommen: Dokumentieren Sie die Vision so einfach wie möglich. Das kann eine Liste von Stichpunkten sein oder Skizzen, die Sie auf einem echten oder virtuellen Whiteboard aufzeichnen. Im Laufe des Projekts wird diese Vision immer klarer. Sie bekommen ein besseres Verständnis für das zu lösende Problem und Ihre potenzielle Lösung.

Diese Dokumentation ist als Übersicht gedacht, versuchen Sie also, sie allgemein zu halten. Später können Sie im Code selbst weitere Details hinzufügen. In einem UML Diagramm werden zum Beispiel repräsentative Abläufe erwähnt, aber keine detaillierten Funktionen angegeben. Ihre systematische Darstellung hilft Ihnen, zu den Details zu navigieren, anstatt Ihre Vision mit zu vielen Einzelheiten zu überladen.

Sie können auch einen iterativen Ansatz mit selbstdokumentierendem Code wählen: Code mit einer Struktur und Syntax, wodurch die Funktionsweise des Codes ohne Kommentare oder zusätzliche Dokumentation verständlich wird. Ich habe zum Beispiel an einigen Stellen auf meiner eigenen Website festgestellt, dass der von mir programmierte Code schwer zu verstehen war. Zum Zeitpunkt der Erstellung war der Code für mich ganz klar. Zwei Wochen später sah das dann ganz anders aus. Ich war mir sicher, dass jemand meine Seite gehackt und meinen Code zerstört hat! Also nahm ich Verbesserungen vor: Ich änderte die Namen und die Struktur. Wenn ich den Code das nächste Mal aufrufe, verstehe ich ihn dann in der Regel besser. 

Integrieren Sie die Dokumentation in Ihre Entwicklungsarbeit

Stellen Sie sich vor der Erstellung eines Dokuments die Frage: Gibt es eine Möglichkeit, dieses Dokument so zu erstellen, dass es besser zu dem passt, was wir bereits tun?

Mithilfe einer ausführbaren Dokumentation können Sie Details erfassen, ohne zusätzliche Arbeit zu verursachen. Ich möchte das anhand eines Beispiels erklären. Ich habe früher einmal mit einem Unternehmen zusammengearbeitet, das einen fest definierten Prozessschritt hatte: Man musste dort dokumentieren, wie man einen Modultest für seinen Code durchführt. Es war ein manueller Prozess, der irgendwann überflüssig wurde.

Versuchen Sie, anstelle eines dokumentierten manuellen Prozesses automatisierte Modultests durchzuführen. Anstatt also zu dokumentieren, wie sich der Code verhält, erstellen Sie Tests, die sicherstellen, dass sich der Code auf eine bestimmte Weise verhält. Sobald der Code den Vorgaben nicht mehr entspricht, wird der Test fehlschlagen. Mit der testgesteuerten Entwicklung sorgen Sie ganz automatisch dafür, dass die Tests und der Code synchron bleiben – wobei das erneute Testen praktisch kostenlos ist.

Die Tests werden also zur Dokumentation. Sie zeigen Ihnen eindeutig, wie der Code funktionieren soll, während er in einer natürlichen Sprache wie Englisch zweideutig wäre und es immer auch Spielraum zur Interpretation gäbe.  Ein Dokument kann veraltet sein, aber die Tests spiegeln immer aktuelle Informationen wider, ohne zusätzliche Arbeit zu verursachen. Das kostengünstigste Dokument ist das, das Sie gar nicht erst verfassen müssen.