Die verschiedenen Arten der Softwaredokumentation

Grundlegend wird in diesem Beitrag zwischen drei Arten der Dokumentation unterschieden.

Definition der Dokumentationen:

• Benutzer Dokumentation
• Dokumentation der Architektur
• Technische Dokumentation der einzelnen Funktionen

1.) Benutzer Dokumentation
Sie beschreibt den gesamten Funktionsumfang der Software und hilft Benutzern mit ihrem Umgang. Dieser Dokumentation könnte ein eigener Beitrag gespendet werden, da es ein sehr umfangreiches Thema ist. Folgend wird aber nur auf Details der technischen Dokumentationen eingegangen.

2.) Dokumentation der Architektur
Es ist eine der wichtigsten und leider oft vernachlässigten Dokumentationen in der Softwareentwicklung. Sie wird in Form einer Grafik (im Folgenden „Big Picture“ genannt) dargestellt. Auf dem Big Picture werden die Aufgabengebiete jedes autarken Bereiches der Software aufgezeigt und das Zusammenspiel derer. Diese Dokumentation ist wichtig, um die logische Trennung der Funktionalitäten in den jeweiligen Schichten definieren und einhalten zu können.

Sie gehört hoch frequentiert für jeden Entwickler geschult und für alle Beteiligten zur Sichtung, zum Beispiel im Intranet, bereitgestellt. Jeder Entwickler muss genau wissen in welchem Bereich er arbeitet, damit dort auch nur die Funktionalität entwickelt wird, die für den jeweiligen Bereich definiert ist.
Das Big Picture sollte auch bei jeder Planung vorliegen, um aufzeigen zu können, welche Bereiche die geplante Entwicklung betrifft.

Das Big Picture und der Code.
Das Wichtigste am Big Picture ist, dass diese Dokumentation mit dem Code übereinstimmt und sich dort auch anhand von Bezeichnern wiederfindet. Somit ist gewährleistet, dass Entwickler viel leichter einer Vermischung der Schichten entgegen wirken können.

Hierzu ein kleines Beispiel aus meinem aktuellen Projekt buttermilk.
Es zeigt einen Ausschnitt des Big Picture, bei dem es sich um den EJB Part der Server Komponente handelt. Eine genauere Erklärung der einzelnen Bereiche finden Sie im Beitrag Architektur.

3.) Technische Dokumentation der einzelnen Funktionen
Häufig wird diskutiert, was genau für eine Funktionserweiterung der Software dokumentiert werden muss. Mein Tipp, so wenig wie nötig!

Werkzeuge wie zum Beispiel JIRA oder Redmine bieten heute eine perfekte Grundlage zur Verwaltung und Dokumentation vorhandener oder geplanter Funktionen. Aufgaben können hier meist in Form eines „Ticket“ definiert werden. Einem Ticket können Beschreibungen, Dateien, Links und Weiteres zur Erklärung beigefügt werden. Ein sehr guter Platz für einfach gehaltene UML Diagramme.

Es sollte allerdings klar definiert sein, welche Daten hier festgehalten werden dürfen und welche nicht. Denn zu viele Informationen für eine Funktionsbeschreibung erschweren den Umgang und verschwenden kostbare Zeit.

Dokumentation im Programmcode

Von jeglichen Kommentaren im Code rate ich ab. Aus meiner Erfahrung heraus stimmen sie am Wenigsten mit der Beschreibung einer Funktion überein. Meist wenig oder gar nicht gepflegt, tragen sie nur zur Verwirrung bei.

Guter Programmcode braucht keine Kommentare! Ich bin ein Freund von „readable Code“, der mit jeder Hochsprache perfekt umsetzbar ist. Hierzu finden sich unzählige Beitrage im Netz, weshalb es hier nicht weiter ausgeführt wird.

Dokumentationen aktuell halten

Bei der Aktualität der Dokumentationen gibt es klare Unterschiede.

Dokumentationen die aktuell gehalten werden müssen:

• Benutzerdokumentation
• Big Picture

Bei den Dokumentationen der fortlaufenden Entwicklung sieht es schon ganz anders aus. Sie werden nur solange aktuell gehalten, bis die Funktion fertig gestellt ist. Ab diesem Zeitpunkt darf die Dokumentation altern.
Ist also eine Funktion abgenommen und mit dem Release fest verankert, altert auch ihre Dokumentation und darf nicht mehr geändert werden. Eine Änderung der bestehenden Funktion ist eine neue Aufgabe und bedingt einer neuen, eigenen Dokumentation.

Fazit

Software, die auf die hier aufgeführte Art und Weise dokumentiert wird, erleichtert den Umgang und spart Zeit. Neu hinzugekommene Entwickler können sich sehr schnell einarbeiten und ohne lange Anlaufzeit mitwirken.