Die andere Seite des agilen Manifests – Dokumentation in agilen Projekten
In dieser Episode widme ich mich mit der anderen Seite des agilen Manifests – Teil 1: Dokumentation in agilen Projekten.
Viele Teams interpretieren das Agile Manifest so, dass sie auf Dokumentation verzichten können, weil dort steht:
👉 „Funktionierende Software mehr als umfassende Dokumentation.“
Doch das bedeutet nicht, dass Dokumentation keine Rolle spielt – sondern dass sie nur so umfangreich wie nötig, aber so schlank wie möglich sein sollte. Aber was bedeutet das konkret für agile Teams? Welche Dokumentation wird wirklich gebraucht und für wen?
Warum ist Dokumentation ein umstrittenes Thema in agilen Teams?
Viele von uns kennen es aus klassischen Wasserfall-Projekten: Detaillierte Spezifikationen, Pflichtenhefte, Testpläne und Code-Dokumentationen wurden oft seitenweise erstellt – aber kaum genutzt. Dokumentation wurde mehr aus bürokratischen oder haftungsrechtlichen Gründen geschrieben als zur tatsächlichen Unterstützung des Teams oder der Nutzer.
Mit der Einführung agiler Methoden kam dann der Gegentrend: Viele Teams verstanden Agilität als eine Art „Freibrief“, um Dokumentation ganz wegzulassen. Das führte aber schnell zu Problemen, insbesondere wenn neue Teammitglieder hinzukamen oder Fehler schnell gefunden und behoben werden mussten.
Die Wahrheit liegt – wie so oft – in der Mitte. Gute agile Teams dokumentieren nur das, was wirklich Mehrwert bietet.
Technische Dokumentation: Was braucht das Team?
Für Entwickler ist die wichtigste Frage: Wo finde ich die relevanten Informationen, wenn ich an einem bestimmten Code arbeite?
In vielen Unternehmen wurde früher verlangt, den Quellcode in separaten Word-Dokumenten abzulegen. Aber das war völlig unpraktisch – niemand hat diese Dokumente genutzt oder aktuell gehalten.
Heute sind moderne Praktiken gefragt:
✅ Dokumentation direkt im Code (z. B. durch aussagekräftige Kommentare oder Readme-Dateien)
✅ Wikis oder Confluence-Seiten, die regelmäßig gepflegt werden
✅ GitHub/GitLab Flow, wo wichtige Änderungen nachvollziehbar und dokumentiert sind
✅ Automatisierte API-Dokumentation (z. B. mit Swagger für REST-APIs)
Der Schlüssel ist: Die Dokumentation sollte dort sein, wo die Entwickler arbeiten – und nicht in separaten, schwer auffindbaren Dokumenten.
Ein hilfreiches Gedankenexperiment:
Stell dir vor, du kommst als neuer Entwickler ins Team. Welche Informationen brauchst du, um schnell produktiv zu werden?
Wenn das Team diese Frage beantwortet, hat es bereits die Grundlage für eine sinnvolle technische Dokumentation geschaffen.
Benutzer-Dokumentation: Was braucht der User?
Neben der technischen Dokumentation gibt es noch eine weitere Perspektive: Wie erfährt der Endanwender, wie das System funktioniert?
Gute Benutzer-Dokumentation ist nicht einfach eine Anleitung, sondern ein wichtiger Teil der User Experience (UX). Ein ideal gestaltetes System kommt sogar weitgehend ohne Dokumentation aus, weil es intuitiv bedienbar ist.
Dennoch gibt es einige Szenarien, in denen Dokumentation für den Benutzer unverzichtbar ist:
🛠 Installations- und Einrichtungsanleitungen – insbesondere bei komplexeren Softwarelösungen
📖 Kurze, prägnante Handbücher – am besten online verfügbar und aktuell gehalten
💬 Interaktive Tooltips und Chatbots – um dem Nutzer direkt im System Hilfe anzubieten
Hier gilt die Devise: Die beste Benutzer-Dokumentation ist die, die man nicht braucht – die schlechteste ist die, die fehlt!
Die Bedeutung der Definition of Done (DoD)
Ein häufiger Fehler in agilen Teams ist es, Dokumentation als „optional“ zu betrachten. Doch wenn Dokumentation wirklich gebraucht wird, sollte sie Teil der Definition of Done (DoD) sein.
Das bedeutet:
✔ Eine User Story ist erst dann „fertig“, wenn auch die erforderliche Dokumentation erstellt wurde.
✔ Das Team entscheidet gemeinsam, wie und wo dokumentiert wird.
✔ Dokumentation sollte schlank und pragmatisch sein, aber niemals komplett weggelassen werden.
Eine gute Praxis ist es, sich immer zu fragen:
„Welche Informationen werden in einem halben Jahr noch nützlich sein, wenn wir oder jemand anderes an diesem Code arbeiten?“
So kann unnötiger Ballast vermieden und gleichzeitig sichergestellt werden, dass wichtige Informationen erhalten bleiben.
Fazit: Dokumentation sinnvoll gestalten, nicht abschaffen!
Agile Entwicklung bedeutet nicht, Dokumentation zu ignorieren – sondern sie bewusst zu gestalten. Die zentrale Frage sollte immer sein:
„Wer braucht welche Information und warum?“
💡 Entwickler brauchen eine technische Doku, um effizient arbeiten zu können.
💡 Endanwender brauchen eine verständliche Anleitung, um die Software optimal zu nutzen.
💡 Produkt-Teams sollten darauf achten, dass nur das dokumentiert wird, was wirklich notwendig ist – aber nichts fehlt, was gebraucht wird.
Und das Wichtigste: Dokumentation sollte dort sein, wo sie gebraucht wird – nicht in veralteten Word-Dokumenten auf Netzlaufwerken.
Links und Ressourcen
- Blogartikel: Dokumentation in agilen Projekten – so geht’s
- IX Developer 3/2013: André Pflüger, Thorsten Cziharz: „Späte Folgen – Nachdokumentation in agilen Projekten”
Hast du Erfahrungen mit Dokumentation in agilen Teams gemacht? Wie handhabt ihr das in eurem Unternehmen? Schreib mir auf LinkedIn oder vereinbare einen Termin
Dein agilophiler Frank
Weitere Episoden des agilophil Podcasts findest du auf der Übersichtsseite Podcast.
PS: Nachtrag 01/2025 – Diese Folge wurde aufgenommen bevor die KI Einzug in das alltägliche Arbeitsleben gehalten hat.