Das richtige Maß an Dokumentation in agilen Projekten

Die Dokumentation in einem agilen Projekt gibt öfters Anlass für Diskussionen unterschiedlicher Lager: Die einen kritisieren die mangelnde Dokumentation. Es scheint, als wäre alle alles Wichtige nur in den Köpfen weniger. Die anderen kritisieren die sinnlose Produktion von Papiermüll, den sowieso kein Mensch liest. Wie kann es sein, dass solch völlig gegensätzliche Positionen durchaus vernünftig klingen und so wenig vereinbar scheinen? Wird hier eventuell „Dokumentation“ falsch verstanden? Und welches Maß an Dokumentation ist das richtige?

Dokumentation hat keinen Wert

Ein Projekt hat immer ein Ziel: es soll ein Produkt erstellt oder Ergebnis erzielt werden, welches die Welt ein klein wenig besser macht – oder zumindest dem Auftraggeber ein Return on Invest verheißt. Das Ziel ist (zumindest meistens) nicht Papier zu erzeugen.

In der Softwareentwicklung, in der ich mich überwiegend bewege, ist die Erstellung einer Anwendung das Ziel. Kein Kunde oder Benutzer sieht jemals die Code-Dokumentation. Selbst das Handbuch oder die Online-Hilfe werden so gut wie nie genutzt. Und falls doch mal jemand zum Handbuch greift, ist das selbstverständlich ein klares Zeichen von schlechter Usability und eines miserablen Nutzererlebnisses. Hier scheinen sich auch alle einig.

Da wundert es nicht, dass die Dokumentation keinen Wert zu haben scheint. Aber ist das so? Wieso wird dann so oft doch dokumentiert? Wieso beschwert sich dann überhaupt jemand über „mangelnde Dokumentation“? Wer braucht Dokumentation überhaupt?

Dokumentation ist lästige Pflicht

Produkte (und dazu gehört auch Software) müssen mit einem Handbuch ausgeliefert werden. Andernfalls ist es ein Mangel. Je nach Branche und Produkt kann es hier noch zahlreiche weitere Auflagen geben.

Um diesen Pflichten nachzukommen, muss wohl oder übel dokumentiert werden. Die Zeit und Kosten dafür müssen im Projekt daher berücksichtigt werden.

Kein Wunder, wenn da Unmut im agilen Team entsteht. Hier wird leider oft versäumt zwischen „Pflicht“ und „Pflicht“ zu unterscheiden. Gerade in größeren Konzernen ist es üblich jede Menge „Pflichten“ zu haben, die vom Unternehmen selbst auferlegt werden. Stehen sie der eigentlichen Arbeit im Weg, so werden sie zurecht angeprangert und in Frage gestellt.

Meist wird jedoch nur schlichtweg versäumt zu kommunizieren, weshalb es diese oder jene Pflicht gibt. Rechtliche Pflichten werden schnell akzeptiert. Firmeninterne Regelungen hingegen bedürfen öfters mehr Erläuterungen, die man sich angesichts der aufkeimenden Diskussionen gerne erspart. Kein Wunder, wenn dann die Pflicht zur Dokumentation als lästig wahrgenommen wird. Wer hier noch mit optionaler Dokumentation (z.B. Code-Dokumentation, Architekturdokumentation, Konzepten, Anforderungslisten oder gar Personas und Nutzungskontexten) daherkommt wird argwöhnisch betrachtet.

Dokumentieren ist nicht agil

Agil ist es am Produkt zu arbeiten – und nicht an der Dokumentation. Da sind sich alle einig. Nicht umsonst hat man sich auf die Werte der agilen Softwareentwicklung per Manifests geeinigt: „[Wir schätzen] Funktionierende Software mehr als umfassende Dokumentation.“

Mit anderen Worten: Dokumentation kostet Zeit, die auf Kosten der eigentlichen Softwareentwicklung geht.

Was als Reaktion auf das frühere Wasserfallmodell entstand, in dem sehr viel Dokumentation im Vorfeld entstand, hat unlängst ins Gegenteil umgeschlagen. Das Feindbild „Dokumentation“ ist selbst in Führungsetagen vorgedrungen, in der man sich Jahrzehnte zuvor nur allzu gerne an Schriftstücke geklammert hat.

Zusätzlich rückt seit Jahren der Kunde bzw. der Nutzer immer weiter in den Mittelpunkt aller betrieblichen Aktivitäten. Themen wie Usability, User Experience (UX), User Centered Design (UCD) oder Design Thinking sind in den agilen Teams angekommen. Auch hier konzentriert man sich mehr auf was die Nutzer sagen und tun, als auf irgendwelche alten eigenen Vorhaben, Pläne oder Konzepte.

Da stellt sich schnell die Frage: wozu noch Konzepte oder Pläne erstellen, wenn man das alles flexibel halten will?

Fehlendes Dokumentieren kann teuer sein

Meetings

Schnell sind sie angesetzt. Denn etwas zu mal eben zu erklären geht meist fünf bis zehn Mal schneller, als es aufzuschreiben. Da erscheint es wenig sinnvoll zu dokumentieren. Es wird kurzerhand ein Meeting angesetzt und alles wird mündlich vermittelt. Dies scheint eine gute Lösung zu sein und wird auch oft so praktiziert.

Dabei wird nicht selten außer Acht gelassen, dass die Adressaten diese Information oft zu unterschiedlichen Zeitpunkten benötigen. Jene, die gerade diesen Bedarf für sich selbst noch nicht absehen können, hören weniger aufmerksam zu und vergessen das gesagte schnell wieder, da es wenig Relevanz für sie hat.

Wird das Thema dann später relevant, muss das gesagte meist nochmal wiederholt werden. Diese zeitliche Entkopplung sorgt für mehrfache Wiederholungen und kann den Aufwand einer einmaligen Dokumentation deutlich übersteigen.

Einarbeitung in Code

Auch schlecht dokumentierte Schnittstellen im Code kosten die Entwickler viel Einarbeitungszeit. Anstatt einen Code einfach und schnell verwenden zu können, müssen sich die Entwickler in die Funktionsweise im Detail einlesen, um zu verstehen, wie dieser Code zu verwenden ist. Auch hier würde eine einmalige Dokumentation wiederholte Zeit und damit Kosten sparen.

Nachschlagewerke

Niemand kann sich alles merken. Gerade bei Projekten mit mehr als 2000 Stunden Aufwand häufen sich Use Cases, Anforderungen, Bugs, Arbeitslisten, Pläne, etc. an, die sich niemand merken kann oder will. Wird hier zu sehr an Dokumentation gespart, verdammt man sich schnell zu einem Drehen im Kreis.

Fluktuation im Team

Bei langlaufenden Projekten kommen immer wieder neue Personen ins Team und müssen eingearbeitet werden. Auch hier ist ein vorhandener Grundstock an Dokumenten als Quelle hilfreich. Insbesondere dann, wenn Mitarbeiter mit wichtigem Wissen das Projekt verlassen, ist es unerlässlich dies an die Nachfolger zu übergeben. Kommt der Nachfolger erst Monate später, ist Dokumentation oft das einzige, was dieses Wissen transportiert.

Nicht zu dokumentieren ist auch keine Lösung. Das Minimum-Prinzip ist hier keine gute Option und eine schlechte Heuristik und kostet im Endeffekt viel Zeit und Geld.

Wann man dokumentieren sollte

Um zu bestimmen, wann eine Dokumentation zweckdienlich ist und wann nicht, muss man sich auf den eigentlichen Zweck von Dokumenten zurückbesinnen.

Das geschriebene Wort hatte schon seit jeher einen zentralen Zweck: die Zeit zu überdauern. Denn unser Gedächtnis ist flüchtig und ungenau. Dieser Zweck hat sich bis heute nicht geändert. Und es ist der wichtigste Grund, wieso man überhaupt dokumentieren sollte, auch wenn man nicht dazu verpflichtet ist. Geht Wissen verloren, ist es meist schwer wieder zu erlangen. Ist der Aufwand der Wiedererlangung größer als der Aufwand der Dokumentation, sollte man dokumentieren.

Regel 1: Man sollte das dokumentieren, was nicht vergessen werden darf.

Die Zeit zu überstehen ist jedoch nicht der einzige Zweck des geschriebenen Wortes. Die Weitergabe und Vermehrung des Wissens war auch schon lange ein wichtiges Ziel. (Dieser Artikel zum Beispiel dient primär der Weitergabe und Vermehrung von Wissen.) Zeichnet ein Text uns einen Gedankenpfad auf oder vermittelt eine Idee, so können wir dem folgen, ohne uns diese Einsicht mühsam selbst erarbeiten zu müssen. Das Schreiben und Lesen dient nicht nur der Bewahrung über die Zeit, sondern auch dem Wissenstransfer von Mensch zu Mensch. Dokumentation hilft, sich nicht zu wiederholen.

Regel 2: Man sollte das dokumentieren, was zum dritten Mal gesagt wurde.

Genauso flüchtig wie die Worte sind, so flüchtig ist auch der Kontext, für den sie relevant waren. Eine mündlich gegebene Hilfestellung hat vielleicht ihren Zweck bereits erfüllt und braucht nicht aufgeschrieben zu werden. Dies wäre Zeitverschwendung. Wird diese Hilfestellung jedoch bereits zum dritten Mal gebraucht, so lohnt es dies aufzuschreiben. (Die Zahl 3 ist hier lediglich ein guter Erfahrungswert. Wichtig ist nur, dass es ein klares Limit gibt.)

Diese Regeln sind Faustregeln, die helfen in agilen Teams schnell und leicht zu entscheiden, was man dokumentieren sollte und was nicht.

Auffindbarkeit der Dokumentation

Oft wird sogar dokumentiert (bzw. noch schlimmer: mehrfach dasselbe dokumentiert) und es entfaltet trotzdem nicht den gewünschten zeitsparenden Effekt. Dies liegt dann meist an der Unauffindbarkeit dieser Dokumente.

Dokumentation ist meist vielfältig: Während der Code seine Dokumentation im Quellcode trägt, sind Architekturentscheidungen oft separat dokumentiert. Ticketsysteme können mehr oder minder integriert sein. Deren Verwendung ist, sofern überhaupt dokumentiert, ebenfalls außerhalb des Ticketsystems zu suchen. Die Hausordnung hängt an der Wand und der Arbeitsvertrag in der Personalakte. Dokumente sind nie an einem Ort und ab einer gewissen Größe bzw. Komplexität stark verteilt. In so einem Umfeld sind Informationen oft kaum zu finden.

Zudem benötigt jede Rolle im Team unterschiedliche Dokumente. Nicht jedes Dokument ist für jede Rolle geeignet.

Regel 3: Dokumentation sollte Rollen-bezogen auffindbar gemacht werden.

Dokumentation ohne Auffindbarkeit ist in der Tat eine Produktion von „Waste“. Daher empfiehlt es sich, pro Rolle einen zentralen Einstiegpunkt zu hinterlegen, von dem aus alle anderen Dokumente zu finden sind. Idealerweise ist dieser Ort systematisch und hierarchisch organisiert. Nicht umsonst haben Bibliotheken einen Index. Niemand will alle Bücher lesen, wenn er eine konkrete Antwort auf eine konkrete Frage hat.

Angesichts der heterogenen Dokumentationslandschaft ist es i.d.R. kaum einem Team möglich diese Landschaft vollständig zentral durchsuchbar zu gestalten. Prozessänderungen erzeugen zudem Brüche in der Systematik dieser Landschaft. Dies erschwert die Suche. Es genügt meist jedoch ein zentraler Einstiegsort und kurze Erläuterungen was wo zu finden ist. Die einzelnen Systeme (DMS, Code Repository, Wiki oder Ticketsystem) bieten dann meist eine Suchfunktion. Aber auch hier ist eine Einstiegshilfe sinnvoll. Denn nicht jeder weiß gleich, wonach er suchen muss.

Dokumentation, die mit Respekt der eigenen Zeit und der Zeit des Lesenden gegenüber erzeugt wird, sollte immer mehr Zeit sparen, als es erzeugt.