Dokumentation zählt nicht zu den beliebtesten Tätigkeiten von Softwareentwicklern.
Während Quellcode relativ gut dokumentiert wird, findet Projekt-Dokumentation (Wartungshandbücher, Projekthandbücher, Anwenderdokumentationen) häufig nicht oder nicht ausreichend statt.
Warum ist das so? Warum ist die Quellcode Dokumentation für Entwickler vergleichsweise einfach durchführbar?
Für CosmoCode sind diese Fragen zentral – geht es im sprintDoc Forschungsprojekt doch darum, Dokumentationsprozesse in agile Entwicklungsmethoden zu integrieren.
Ich habe mir die Mühe gemacht und (subjektiv) die Gründe dafür zusammengetragen; inspiriert durch die Teilname an den Analyseworkshops im Forschungsprojekt. Diese Aufstellung stellt einen subjektiven Zwischenstand dar; nach Abschluss der Analysephase werden wir an dieser Stelle aufbereitete Informationen darstellen.
Grund 1: Toolintegration
Dokumentation des Quellcodes wird im Quellcode gemacht. Das bedeutet, dass der Entwickler sich keine Gedanken um das Dokumentationswerkzeug machen muss – er benutzt die selben Instrumente wie bei der Softwareentwicklung.
Grund 2: Vorgegebene Struktur
Die Quellcode Dokumentation erfolgt häufig direkt an der Funktion oder dem Modul. Es gibt keine separate Struktur der Dokumentation; es muss also auch keine separate Struktur geschaffen oder gepflegt werden.
Grund 3: Vorgegebener, existierender Integrationspunkt
Nicht nur die Struktur der Dokumentation ist vorgegeben, sondern auch „das Dokument“, wo dokumentiert wird. Es wird keine Zeit zum Suchen des Dokumentationsortes benötigt; es wird keine Zeit zur Prüfung benötigt, ob ein bestehender Dokumentationsort verwendet werden kann oder einer neuer geschaffen werden muss.
Grund 4: Definierter Use Case & Motivation
Ganz wichtig – der Use case für die Dokumentation ist klar: Quellcode Dokumentation soll in erster Linie (*) dazu dienen, den Quellcode zu verstehen. Dokumentation von Entwickler für Entwickler. Der Nutzen dieser Dokumentation wird jedem Entwickler schlagartig klar, wenn er fremden oder eigenen Code bearbeiten muss. Denn wie sagte Joel Spolsky so schön: „Its harder to read code than to write code“.
(*) Dazu gehört auch die Dokumentation von APIs.
Grund 5: Klare Anforderungen, klarer Kontext, klare Granularität
Wenn „nur“ Funktionen dokumentiert werden, ist die Dokumentation erledigt, wenn das Verhalten der Funktion/des Moduls dokumentiert wird. Systemübergreifendes Verhalten wird bestenfalls dann dokumentiert, wenn sich Effekte der Funktion woanders zeigen. Dies bedeutet, dass man bestehende Dokumentation hinsichtlich ihrer Korrektheit gut prüfen und anpassen kann. Man muss auch keine anderen Dokumentationsorte sichten und auf Korrektheit prüfen.
Grund 6: Integration in bestehende Prozesse, Publishing
Dokumentation wird zusammen mit dem Quellcode verwaltet; die Versionierung bekommt man frei Haus. Mehr noch: bestehende Deploymentverfahren können dazu genutzt werden, die Publikation über Dok-Generatoren automatisiert anzustoßen.
Was kann man daraus lernen?
- Dokumentationsaufgaben benötigen (wie Softwareentwicklung auch) klare Anforderungen.
- Auch Dokumentatinen benötigen eine Approval und eine Definition of done
- Dokumentationen sollten gemeinsam mit der Software gemanaged werden. Versionen der Software sollten mit Versionen der Dokumentation gekoppelt sein.
- Dokumentationen sollten eine klare, vorgegebene Struktur haben. Idealerweise sollte sich aus der Softwareanforderung/ bzw dem Quellcode die Stelle in der Dokumentation identifizieren lassen.
- Dokumentationssysteme sollten mit den Werkzeugen der Entwicklung verknüpft sein. Also mit der IDE, oder dem Aufgaben/Ticket/PM-System