THE NEED FOR DOCUMENTATION GUIDELINES

Es soll Gerüchte geben, dass Dokumentationen von Softwarearchitekturen sowie Moduldokumentationen an sich nicht zu den beliebtesten Aufgaben eines Softwareentwicklers zählen. Die möglichen Gründe dafür und einen Ansatz zur Aufstellung von Dokumentationsrichtlinien, die diese Aufgabe einfacher gestalten können, möchte ich in diesem Artikel vorstellen.

In diesem Artikel setze ich den Fokus auf Dokumentationen von Software als Gesamtmenge an Strukturen, Modulen und Komponenten. Hierbei möchte ich Dokumentationen direkt im Quellcode, wie bspw. Kommentare an Funktions-Header ausschließen.

Ich habe die Erfahrung gemacht, dass in Softwareunternehmen selten einheitliche und wohldefinierte Dokumentationsrichtlinien zur Einhaltung und Hilfestellung vorgegeben werden. Dies beinhaltet auch die Vorgabe für einzusetzende Werkzeuge, wie Modellierungstools für Softwarebausteine, mit denen Relationen, Verantwortlichkeiten sowie Verhalten abgebildet werden können.

Es gibt genügend Gründe, die dafür sprechen, Dokumentationen anzufertigen. Was ist aber nun der Grund, warum sie ungern angefertigt werden?

Aus Erfahrung kann ich sagen, dass eine große Unsicherheit darin besteht, die richtige Einschätzung treffen zu können, was zu dokumentieren ist und vor allem wie. Dazu kommt noch, dass Designentscheidungen und Systeme unterschiedliche Strukturen aufweisen können. Es gibt demnach nicht die einzig richtige Dokumentationsform für alle Anwendungsfälle.

Welches Verhalten muss dokumentiert werden? Müssen Modelle gezeichnet werden, wenn ein Pattern gewählt wurde und erklärt werden, warum jenes implementiert wurde?

Als Beispiel sei hier ein System mit einer Mehrschicht-Architektur genannt. Für eine Komponente einer Client-Schicht spielen ganz andere Aspekte eine Rolle, die für eine Dokumentation notwendig sind, als für Serverkomponenten.

Dokumentationsrichtlinien für alle möglichen Arten von Systemen und deren Verhalten zu erstellen, ist geradezu unmöglich und verursacht nicht nur bei der Auswahl der richtigen Dokumentation, sondern auch bei der Menge an anzufertigen Dokumenten einen unüberschaubaren Aufwand.

Ein erfahrender Softwareentwickler weiß, warum er eine Architektur gewählt hat, welche Verantwortlichkeit welche Komponente besitzt und warum er gerade ein Design favorisiert hat.

Die Schwierigkeit für den Dokumentierenden besteht nun aber darin, einzuschätzen, was eigentlich festgehalten werden muss, damit Kollegen die Zusammenhänge und Gedanken der Neuentwicklung oder Veränderung in bestehenden Architekturen nachvollziehen können. Denn Dokumentationen dienen auch als Diskussionsgrundlage und können zu einem schnellen Überblick verhelfen, wenn Entscheidungen abgesegnet werden müssen oder Reviews durchgeführt werden.

Ein möglicher Ansatz um dieser Unsicherheit entgegenzuwirken, ist, Dokumentationsrichtlinien aufzusetzen.

Der erste Schritt dabei wäre es, zu definieren, was für eine Art Dokumentation am Ende überhaupt vorliegen soll. Das könnte zum Beispiel ein Word-Dokument sein, ein Forum, eine Wiki oder eine generierte HTML-Seite.

Ist dies definiert, so gibt es eine Vielzahl an weiteren Festlegungen, die getroffen werden müssen. Ich möchte nur einige nennen, um Impulse zu geben und um zu verdeutlichen, wie komplex ein initiales Setting für den Aufbau einer Dokumentationsinfrastruktur sein kann.

Weitere Beispiele für zu treffende Entscheidungen:

Welche Stakeholder sind an der Erstellung und der Verwendung beteiligt? Wer muss die Dokumentation bearbeiten können – ist eine Rechteverwaltung für Leserechte und Schreibrechte von Nöten? Dazu kommt auch noch die Auswahl eines Dokumentationstools für die Anfertigung von Modellen.

Auswahl der Stakeholder und die Definition ihrer Anforderungen 

Mein Ansatz für dieses herausfordernde Projekt ist es, ein Team von Stakeholdern zusammenzustellen, die ihre Anforderungen an eine Dokumentation aufstellen.

Wichtig dabei: Ziel ist es, eine Anforderungsanalyse durchzuführen und im ersten Schritt keine Lösung zu entwickeln.

Definition einer Dokumentationsinfrastruktur

Im zweiten Schritt sollte der Fokus auf eine Dokumentationsinfrastruktur gelegt werden. Hier spielen Aspekte wie Zugriffsmöglichkeiten, Versionsverwaltungen und Verfügbarkeit eine Rolle.

Aufsetzen der Dokumentationsrichtlinien

Steht die Infrastruktur, so kann mit der Definition der Dokumentationsrichtlinien begonnen werden. Leider muss ich hier schon vorwarnen, dass die Erstellung von Richtlinien ein langwieriges Projekt ist und höchstwahrscheinlich nicht in einem Rutsch fertiggestellt werden kann.

Auswahl von Werkzeugen und Diagrammarten

Der nächste Schritt wäre nun, Modelltypen je nach Abstraktionslevel auszuwählen. Mit der Auswahl von Modelltypen je nach Abstraktionslevel ist hier bspw. die Rede von der Verwendung von Klassendiagrammen für Dokumentationen von Klassenstrukturen bis hin zu Komponentendiagrammen für Modul-Schnittstellen.

Am besten wird eine kleine Menge an strukturbeschreibenden sowie dynamischen Diagrammtypen festgelegt, die verwendet werden müssen. Die Auswahl der Diagrammarten sollte von Beginn an so klein wie möglich gehalten werden und kann Stück für Stück erweitert werden.

Dazu gehört auch, wie ich finde, eines der größten Herausforderungen, ein Modellierungstool zu finden, das die ausgewählten Diagrammarten zur Verwendung anbietet.

 

Fazit

Wie in diesem Artikel hoffentlich deutlich geworden ist, ist die Dokumentation von Software nicht nur ein sehr wichtiges, aber auch ein umso herausfordernderes Software Engineering-Thema, das viel mehr Beachtung und Investition verdient, als es derzeit den Anschein hat.

 

Bilder: pixabay.com