Fünf Tipps zur effektiven Dokumentation agiler Projekte

Agilität ist in aller Munde. Einerseits zurecht, schliesslich nehmen Volatilität, Unsicherheit, Komplexität und Mehrdeutigkeit in der Arbeitswelt stetig zu. Agile (Software-) Entwicklung ermöglicht es, durch ein iteratives Vorgehen (bei Scrum z. B. mittels sogenannter Sprints), flexibel auf vielschichtige und sich verändernde Kundenbedürfnisse einzugehen. Dadurch hebt sie sich von traditionellen Wasserfallansätzen ab, bei denen zunächst sämtliche Anforderungen dokumentiert werden, bevor sie zu Design, Implementierung und Test übergehen.

Andererseits zeigen sich bei der agilen Entwicklung auch Nachteile. So wird in der Praxis die Dokumentation oft vernachlässigt. Die Abneigung gegenüber Dokumentationen im agilen Kontext ist durchaus verständlich, entsprangen agile Praktiken doch genau einer Abkehr von der umfassenden und frühzeitigen Spezifikation und Dokumentation, wie sie in Wasserfallentwicklungen praktiziert wird. Das erschien erforderlich, da bei Wasserfallprojekten nicht selten jahrelang dokumentiert und spezifiziert wird und damit hunderte Seiten Papier gefüllt werden, nur um dann bei der Entwicklung oder beim Testing festzustellen, dass ein Teil des Beschriebenen gar nicht mehr den Userbedürfnissen entspricht. Schliesslich fällt es Stakeholdern – insbesondere in frühen Projektphasen – schwer, ihre Bedürfnisse präzise auszudrücken, da sie diese selbst nur ansatzweise kennen. Daraus ergeben sich ungenaue Anforderungen. Als Reaktion darauf wurde im agilen Manifest folgender Wert verankert: «(Wir schätzen) funktionierende Software mehr als umfassende Dokumentation» [1].

Damit war allerdings – im Unterschied zu gängiger Praxis – nicht gemeint, man solle komplett auf Dokumentation verzichten. Vielmehr verändert sich einfach ihre Gewichtung im Projekt. Um den Konsequenzen fehlender Dokumentation auf den Grund zu gehen, ist es sinnvoll, zwischen unterschiedlichen Dokumentationsarten zu unterscheiden.

Welche Arten der Dokumentation gibt es?

Wir unterscheiden in diesem Beitrag zwischen drei Arten der Dokumentation:

• Code-Dokumentation: Beschreibt, was der Code macht. Zur Nachvollziehbarkeit für andere Programmierer:innen.
• Dokumentation der Geschäftslogik: Erläutert die Funktionsweise des Produkts sowie die zugrundeliegende Geschäftslogik. Dient dem gemeinsamen Verständnis des agilen Teams und einer allfälligen späteren Weiterentwicklung.
• Anwenderhandbuch: Erklärt die Bedienung des Produkts für die Anwender:innen.

Fehlt die Dokumentation, können Nachteile für das ganze Projekt entstehen. Die Dokumentation ist also mit einem erheblichen Nutzen verbunden, welchen der nächste Abschnitt genauer beschreibt.

Was bringt eigentlich Dokumentation?

• Gemeinsames Verständnis: Alle drei Arten der Dokumentation sind Kommunikationsinstrumente, zwischen Programmierer:innen untereinander, zwischen ihnen und Fachmitarbeitenden oder zwischen dem Entwicklungsteam und den Usern. Fehlt z. B. die Dokumentation der Geschäftslogik, wird das System für die fachlich ausgerichteten Teammitglieder schnell zur Black Box, weil sie nicht mehr verstehen, warum das System so funktioniert, wie es funktioniert.
• Übersichtlichkeit: Insbesondere grosse Projekte werden schnell unübersichtlich. Während die Dokumentation der Geschäftslogik den Teammitgliedern einen Gesamtüberblick über das System ermöglicht, hilft das Anwenderhandbuch den Anwender:innen dabei, sich schnell im System zurecht zu finden.
• Nachvollziehbarkeit: Fehlt die Dokumentation, werden die Wartung und zukünftige Weiterentwicklung des Produkts erschwert, da man seine Funktionsweise nicht nachvollziehen kann. Zudem entstehen Zusatzaufwände durch umfangreiche Reverse-Engineering-Operationen.

Der Nutzen der Dokumentation ist also erkannt. In der Praxis erweist sich die Dokumentation in agilen Projekten aber nach wie vor als anspruchsvoll.

Wie also kann Dokumentation in agilen Projekten gelingen?

Tipp 1: Sich auf den Zweck der Dokumentation besinnen

Dokumentation ist kein Selbstzweck. In erster Linie ist sie ein Kommunikationsinstrument und dient der Wissensvermittlung. Sie schafft ein gemeinsames Verständnis und befähigt User, zukünftige Entwickler und Supportmitarbeitende, die Bedienung bzw. die Funktionsweise des Produkts zu verstehen und adäquat damit zu arbeiten. Im Umkehrschluss sollte die Dokumentation auf die verständnisfördernden Inhalte reduziert werden, wie Tipp Nummer 2 verdeutlicht.

Tipp 2: Dokumentation effizient gestalten

In traditionellen Entwicklungsansätzen wird jedes kleinste Detail des Produkts dokumentiert, was mit grossem Aufwand und Ressourceneinsatz verbunden. Da Dokumentation in agilen Projekten «nur» ein Mittel zum Zweck ist, sollte sie effizient gestaltet werden. Folgende Ansätze können dabei helfen:

• «Reduce to the max»: Die Dokumentation der Geschäftslogik muss nicht perfekt sein, sondern gerade gut genug, um ihren Zweck zu erfüllen. Bspw. mit Bulletpoints statt Fliesstext oder einem Fokus auf die wesentlichen Zusammenhänge und Funktionalitäten lässt sich wertvolle Zeit sparen.
• Synergien nutzen: Wird die Code-Dokumentation in der Sprache und Logik des Fachs verfasst, kann sie je nach dem auch als Dokumentation der Geschäftslogik dienen. Das hängt jedoch vom Projektkontext und den gegebenen Rahmenbedingungen ab.

Tipp 3: Dokumentation als Teil des Produkts sehen

In vielen agilen Projekten wird die Dokumentation als mühsame Zusatzarbeit zum Produkt verstanden, dabei ist das Produkt ohne Dokumentation oft unvollständig oder unverständlich. Daher empfehlen wir, die Dokumentation als integralen Bestandteil des Produkts zu verstehen und in die Sprints einzubauen. So können Code-Dokumentationen, die Dokumentation der Geschäftslogik bspw. in die Definition of Done (Kriterien, ab wann eine Anforderung als umgesetzt angesehen wird) aufgenommen werden. Das Anwenderhandbuch hingegen kann vor seiner erstmaligen Erstellung z. B. als eigene Anforderung an das System formuliert und später bei seiner Nachführung ebenfalls in die Definition of Done aufgenommen werden.

Tipp 4: Nur an einem Ort dokumentieren

Dokumentieren kann ein frustrierendes Unterfangen werden, wenn verschiedene Dokumente an verschiedenen Orten abgelegt sind, sie verschiedene Aspekte des Produktes abdecken und alle nur teilweise aktuell sind. Daher empfehlen wir, nur an einer zentralen Stelle zu dokumentieren. Als Motto gilt: «Don’t repeat yourself». Das wird jedoch umso schwieriger, wenn mit Tools gearbeitet wird, welche keine Verweise zwischen den Bestandteilen der Dokumentation ermöglichen. Daher gilt es, Werkzeuge zu verwenden, welche Kollaboration und Verweise zulassen und idealerweise dynamisch aufgebaut sind. Folglich eignet sich eine gemeinsame Ablage inkl. gleichzeitiger Bearbeitungsmöglichkeit besser als ein persönlicher Ordner. Ein kollaboratives Dokumentationswerkzeug (z. B. Wiki-System) ist beispielsweise zweckmässiger als ein statisches Format wie Word.

Tipp 5: Den richtigen Zeitpunkt wählen

In Projekten kann kontinuierlich oder zu einem spezifischen Zeitpunkt dokumentiert werden. Wie am besten vorgegangen wird, hängt einerseits vom spezifischen Projekt und andererseits von der Art der Dokumentation ab. Während Anwendungshandbücher tendenziell erst relativ spät ein erstes Mal verfasst werden sollten, um allzu viele Überarbeitungen zu vermeiden, empfiehlt es sich, die Dokumentation der Geschäftslogik kontinuierlich, z. B. jeweils am Ende eines Sprints, nachzuführen. Code-Dokumentationen sollten grundsätzlich laufend ergänzt werden, damit der Code jederzeit nachvollziehbar ist.
Obschon jedes Projekt anders ist und sich die Anforderungen und spezifische Ausgestaltungen der Dokumentation unterscheiden, können die genannten fünf Tipps als Leitlinie dienen, um erfolgreich in agilen Projekten zu dokumentieren.

Möchten Sie mehr über dieses spannende Thema erfahren oder brauchen Sie Unterstützung in Ihren agilen Projekten? Zögern Sie nicht uns per Telefon unter 058 320 30 00, per E-Mail unter office@app.ch oder mittels des untenstehenden Formulars zu kontaktieren. Unsere Expertinnen und Experten freuen sich auf Ihre Anfrage.