Die agile Dokumentation in der Softwareentwicklung

„Wir sind jetzt agil – wir dokumentieren nicht mehr!“ Oder: „Der Sourcecode reicht als Dokumentation.“ Solche oder ähnliche Aussagen habe ich schon häufig von Softwareentwicklungsteams gehört.

Für die Entwicklung von überschaubaren Systemen mit kürzerer Lebensdauer kann das gut funktionieren. Genauso, wenn das Team, das das System gebaut hat, auch nach der Inbetriebnahme des Systems verfügbar ist, um eventuell aufkommende Fragen von Nutzern oder Systembetreuern zu beantworten.

Schwieriger wird es bei der Entwicklung von komplexen Systemen mit langer Lebensdauer, wie zum Beispiel in der Raumfahrt. Softwaresysteme sind hier gut und gerne über zehn Jahre im Betrieb und müssen über den gesamten Zeitraum gewartet und betreut werden. Viele der an der ursprünglichen Realisierung beteiligten Person haben das Unternehmen dann vielleicht schon wieder verlassen oder arbeiten in anderen Projekten, so dass ihre Unterstützung nicht kurzfristig eingeholt werden kann. Wenn die Dokumentation dann nur im Sourcecode vorliegt, müssen sich projektfremde Personen erst mühsam in den Code einarbeiten. Bei Fehlern im Live-System kann genau das wertvolle Zeit kosten.

Aber selbst, wenn nach mehreren Jahren die ursprünglichen Entwickler noch verfügbar sind, ist damit nicht gesagt, dass sie den Quellcode immer noch so gut verstehen, wie an dem Tag, an dem sie ihn geschrieben haben. Auch wenn alle Informationen irgendwo im Programmtext vorhanden sind, müssen Entwickler wissen, wo genau im Quellcode sie diese finden können. Laut Carola Lilienthal ist ein Entwickler in der Lage, ungefähr 30.000 Zeilen Quellcode zu überblicken – die meisten heutigen Systeme sind allerdings viel größer.¹

Natürlich können eine sinnvoll überlegte Paketstruktur und sprechende Namespaces die Orientierung erleichtern. Aber wie geht es zum Beispiel Mitarbeitern im Support, die vielleicht keinen Zugriff auf den Quellcode haben bzw. die nicht geübt im Lesen von Sourcecode sind? Ohne unterstützende Dokumentation muss sich der Support bei Fragen oft an die Entwickler wenden, die hierdurch immer wieder aus der aktuellen Tätigkeit herausgerissen werden und weniger Zeit für die Entwicklung von neuen Features haben. Evtl. hilft der Einsatz eines SWAT-Teams, doch auch SWAT-Team-Mitglieder verfügen nicht über unbegrenzten mentalen Speicherplatz, um sich über Jahre alle Details zur Funktionsweise einer Software zu merken.

Die Dokumentation im Eigeninteresse

Gar nicht zu dokumentieren kostet langfristig meist mehr Zeit, als am Anfang durch den Verzicht auf Dokumentation eingespart wird. Also wäre es doch theoretisch im eigenen Interesse des Entwicklungsteams, Dokumentation außerhalb des Quellcodes zu schreiben, oder? Leider nur theoretisch. Die Dokumentationserstellung zählt in der Softwareentwicklung (mit einigen wenigen Ausnahmen) eher zu den unliebsamen Tätigkeiten. Ein „notwendiges Übel“ quasi, um das man sich nur kümmert, wenn kein Weg daran vorbeiführt. Falls niemand nach einer Dokumentation fragt, kann das eine Weile gut gehen. Zumindest solange, bis dann besagte Fehler im Live-System auftauchen und alle angestrengt überlegen, welcher Service denn noch mal für was zuständig war.

Verlangt der Kunde oder gar der Gesetzgeber im Zuge einer Softwarelieferung nach einer entsprechenden Dokumentation, kommen „dokumentationsfaule“ Teams früher oder später ins Schwitzen. Manche machen dann „Dokumentationssprints“, in denen alle Teammitglieder zum Projektende – oft über mehrere Wochen – nur noch dokumentieren. Aus eigener Erfahrung weiß ich, dass dies meist ein äußerst mühsames Unterfangen ist. Denn bei sehr komplexen Systemprozessen reichen schon ein paar Wochen oder sogar Tage, um Details beispielsweise über Prozessabläufe zu vergessen. Diese dann aus dem Quellcode zu rekonstruieren, ist oft langwierig und fehleranfällig.

Wahrscheinlich ist es mit der Dokumentation also ein bisschen, wie mit dem guten Vorsatz, mehr Sport zu treiben: Wir wissen alle, dass Sport gesund ist. Trotzdem hindert uns oft unser innerer Schweinehund daran, uns mehr zu bewegen. Wenn dann schließlich das schlechte Gewissen groß genug ist, wird versucht, dies durch lange und intensive Trainingseinheiten zu kompensieren. Prompt stellt sich ein heftiger Muskelkater ein, der dann auf dem Sofa auskuriert werden muss. Wäre es nicht stattdessen besser, regelmäßig und moderat Sport zu betreiben?

Die Dokumentation als Teil des Entwicklungsprozesses

Aber wie schafft es ein Team, den inneren „Dokumentations-Schweinehund“ zu überlisten und Dokumentation zur guten Gewohnheit zu machen? Am besten geht das, wenn die Dokumentationserstellung fest in den Entwicklungsprozess integriert wird.

Manche Teams nehmen die Dokumentation als separaten Punkt in die Definition of Done auf. Bevor ein Ticket als „Done“ markiert wird, muss dann jedes Teammitglied prüfen, ob die Dokumentation eines Features oder einer User Story ausreichend ist. Gegebenenfalls muss er oder sie die Dokumentation erstellen oder ergänzen. Es versteht sich natürlich von selbst, dass die Definition of Done allen Teammitgliedern bekannt sein muss, damit sie auch funktioniert. Ich habe es leider als Coach schon oft erlebt, dass Entwickler sagen: „Wir haben eine Definition of Done – aber ich weiß gar nicht genau, was da drinsteht.“ Damit das nicht passiert, hinterlegt man die Definition of Done am besten gleich im Projektwiki oder hängt sie im Teamraum aus.

Wenn das Team ganz sicher gehen will, dass es die Dokumentationserstellung parallel zur Entwicklung nicht vergisst, legt es sich für jedes zu dokumentierende Ticket eine entsprechende Unteraufgabe mit dem Titel „Dokumentation“ im Sprint Backlog an. So wird das Thema Dokumentation noch expliziter gemacht.

So viel wie nötig, so wenig wie möglich

Der Zeitpunkt der Dokumentationserstellung wäre also geklärt. Aber wie verhält es sich mit dem Dokumentationsumfang? Genauso wie exzessives Sporttreiben ab einem gewissen Trainingspensum nicht mehr gesundheitsfördernd ist, so verhält es sich auch bei der Dokumentation. Zu viele Dokumente können durchaus nachteilig sein, weil der Pflegeaufwand steigt. Wenn Dokumente nicht aktuell gehalten werden, ist dies sogar schlimmer, als wenn es gar keine Dokumente gäbe. Veraltete Informationen in Dokumenten führen zu Missverständnissen zwischen den Projektbeteiligten und mit jedem entdeckten Fehler schwindet das Vertrauen in die Dokumentation. Und es ist wirklich schade, wenn aus diesem Grund keiner mehr die Dokumentation liest, in deren Erstellung einmal viel Arbeit geflossen ist!

Beim Dokumentieren in Softwareprojekten sollte das Motto gelten „So viel wie nötig, so wenig wie möglich.“ Was das genau bedeutet, unterscheidet sich je nach Projektkontext und muss im Team mit dem Product Owner und/oder den Stakeholdern abgestimmt werden. Daher können im Folgenden nur Anregungen gegeben werden.

Typischerweise werden in den meisten Projekten mindestens folgende Dokumente benötigt:

• Benutzerhandbuch
• Betriebshandbuch
• Architekturdokument
• Schnittstellenspezifikation(en)
• Release-Notes
• Testfallspezifikation(en)

Zusätzlich ist es empfehlenswert, ein Dokument zu erstellen, welches einen groben Systemüberblick bietet. Dieses Dokument sollte die Produktvision, die wichtigsten Anforderungen und/oder User Storys, den Systemkontext (wie ist der Scope des zu erstellenden Systems und mit welchen Systemen ist es verbunden), die Stakeholderanalyse, ggf. definierte Personas und das Glossar enthalten. Manchmal ist es auch sinnvoll, dem System zugrundeliegende Geschäftsprozesse separat zu dokumentieren (z. B. durch Use Cases), falls sich diese nicht aus dem Nutzerhandbuch ableiten lassen.

Soweit möglich, sollte man bei der Dokumentation auf Standardtemplates zurückgreifen, um das Rad nicht jedes Mal neu erfinden zu müssen. Für die Dokumentation von Softwarearchitekturen ist das kostenlos erhältliche Template Arc42 weit verbreitet, für den Systemüberblick kann man sich von den Spezifikationsvorlagen Volere oder IEEE 830 inspirieren lassen. Die Komplettversionen dieser beiden Vorlagen sind leider mittlerweile kostenpflichtig, die verlinkten Wikipedia-Artikel geben jedoch einen guten Überblick über die Templatestrukturen.

Dokumentation mit der Lean-Philosophie

Auch wenn Standardtemplates aus eher klassischen Projektkontexten genutzt werden, sollten agile Teams grundsätzlich darauf achten, die Dokumentation schlank zu halten. Hier kann man sich an der Lean-Philosophie orientieren, in der nicht wertsteigernde Tätigkeiten tunlichst vermieden werden sollen. Wenn man dies auf die Dokumentation überträgt, dokumentiert man nur noch das, was man auch während des späteren Systembetriebs noch braucht. Auf Dokumente, die nur während der Entwicklungszeit benötigt werden, wird möglichst verzichtet.

Bei einer schlanken Dokumentation wird beispielsweise kein separates Konzeptionsdokument für die grafische Benutzeroberfläche erstellt. Diese Art der Konzeption kann im Rahmen des Benutzerhandbuchs erfolgen. Man hält dort dann nicht nur den jeweiligen Ist-Zustand des Systems fest, sondern beschreibt für noch nicht umgesetzte Features im selben Dokument auch den Soll-Zustand. Dann tauchen dort z. B. bereits fertig gestellte Eingabemasken mit den Screenshots aus dem aktuellen Release auf, während geplante Eingabemasken durch entsprechende Wireframes oder Scribbles definiert werden. Das entsprechende Backlog-Item für die Implementierung der neuen Eingabemaske verweist auf das entsprechende Kapitel im Benutzerhandbuch. Nachdem die geplante Eingabemaske umgesetzt ist, muss das Entwicklungsteam nur den Wireframe gegen den Screenshot der fertigen Maske austauschen und ggf. einige Details, die sich während der Entwicklung geändert haben, aktualisieren.

Auch bei der Beschreibung von Testfällen kann man so vorgehen – dieser Ansatz ist unter dem Namen Behaviour Driven Development (BDD) bekannt. Testfälle werden hier vor der Implementierung geschrieben und damit gleichzeitig als Anforderungen genutzt. Wenn man dann noch ein strukturiertes Format wie „Given-When-Then“ wählt und das mit einem Tool wie Cucumber macht, können daraus direkt automatisierte Tests generiert werden. So schlägt man mehrere Fliegen mit einer Klappe und spart weitere Entwicklungszeit.

Dokumente wie Quellcode behandeln

Eine Herausforderung gibt es, wenn ein Dokument gleichzeitig Beschreibungen des Ist- und Soll-Zustandes enthält: die Versionierung. Schließlich soll jederzeit der Dokumentationsstand zu einem entsprechenden Softwarerelease abrufbar sein (ohne Soll-Zustand-Beschreibungen für ein zukünftiges Release).

Vielversprechend ist in diesem Zusammenhang der Ansatz „Docs as Code“, bei dem die Dokumentation mit den gleichen Werkzeugen erstellt wird, wie der Sourcecode und auch mit diesem zusammen versioniert wird. Dadurch kann man für die Dokumentation alle Annehmlichkeiten einer modernen Versionsverwaltungssoftware, wie z. B. Git-Featurebranches, nutzen. Die Dokumentation wird in der Regel in einer einfachen Wiki-Markup-Sprache erstellt, die auch Nicht-Entwickler schnell lernen können. Grafiken lassen sich ohne Probleme einbinden und mit den entsprechenden Tools wie z. B. dem Asciidoctor kann die Dokumentation aus der Entwicklungsumgebung in verschiedene Formate, wie z. B. Word, PDF, html und auch Confluence, exportiert werden.

Fazit

Auch agile Teams sollten die von ihnen entwickelten Systeme zusätzlich außerhalb des Quellcodes dokumentieren – und zwar so, dass der Dokumentationsaufwand möglichst geringgehalten und die Dokumentation auch gelesen wird. Diese Art von Dokumentation kann sich ein Team zur guten Gewohnheit machen, indem es Dokumentationsaufgaben über die Definition of Done oder dedizierte Unteraufgaben von Features bzw. Storys in den Entwicklungsprozess integriert. Wenn dann noch das Motto „So viel wie nötig, so wenig wie möglich“ befolgt wird, steht einer agilen und erfolgreichen Dokumentation der Softwareentwicklung nichts mehr im Wege.

 

Hinweise:

Interessieren Sie sich für weitere Tipps aus der Praxis? Testen Sie unseren wöchentlichen Newsletter mit interessanten Beiträgen, Downloads, Empfehlungen und aktuellem Wissen.

[1] Vgl. Lilienthal, Langlebige Softwarearchitekturen, 2. Auflage, Heidelberg, 2017, S. 11

Dies ist ein Best of Blog 2019 Beitrag. Hier können Sie sich die besten Beiträge aus  2019 herunterladen.

Kathrin Herrmann hat im t2informatik Blog weitere Beiträge veröffentlicht, u.a.

Was macht eigentlich t2informatik? Ein Klick hier und Sie wissen es.