Entwicklerdokumentation: das notwendige Übel?

Zugehörige Leistung: Entwicklerdokumentation

Anna M. ist Software-Entwicklerin. Seit kurzem arbeitet sie bei einer Firma, die spezialisierte Erweiterungen für eine kaufmännische Standardsoftware verkauft. Für die Entwicklung dieser Erweiterungen soll Anna das API der kaufmännischen Software verwenden. Aber Anna hat ein Problem. Sie weiß nichts über das API – seine Struktur, die Schnittstellen, die angebotenen Funktionen. Denn das API ist sehr spärlich dokumentiert. Anna findet nur eine kurze Übersicht über die angebotenen Schnittstellen und spärliche Code-Kommentare in den Klassen.

Nicht nur Endkunden erwarten gut dokumentierte Software. Auch Software-Entwickler benötigen sie, um ihre Aufgaben und Ziele zu realisieren. Wird ein Software-System entwickelt, wird es in der Regel auch dokumentiert. Aber die Qualität der Dokumentation unterscheidet sich stark von Produkt zu Produkt und ist oft – wie es Anna erfährt – unvollständig. Auch wächst die Dokumentation nicht immer gleichmäßig mit dem entwickelten System. Manchmal bleibt sie auch aufgrund von Termindruck ganz auf der Strecke.

Dieser Artikel fasst einige Erfahrungen aus unseren Projekten zusammen und bietet eine Meinung  zu den Arten und Wegen zu guter Entwicklerdokumentation. Vielen Dank auch an Stefan Zörner für das Gegenlesen dieses Artikels und seine konstruktive Kritik.

Das unvollständige Puzzle

Man kann die verschiedenen Arten von Entwicklerdokumentation als Puzzle betrachten, die zusammen ein Bild der Software ergeben. In den meisten Projekten finden wir folgende Puzzleteile vor:

• UML-Diagramme
• Technische Konzepte
• Use-Case- und Szenario-Beschreibungen
• Code-Kommentare
• Anforderungen
• Aufgaben und Bug-Einträge

Manchmal fügen sich die Puzzleteile zusammen, oft aber nicht: Dann liegen sie in verschiedenen Formaten verstreut über verschiedene IT-Systeme mit unterschiedlichen Zugriffsrechten. Die Informationen in den einzelnen Puzzleteilen überschneiden sich häufig oder laufen auseinander, wenn sie nicht mehr dem Entwicklungsstand des Systems entsprechen. Die Informationen werden damit wertlos.

Neben verstreut herumliegenden Puzzleteilen gibt es in vielen Projekten die Teile, die ganz fehlen:

• Eine Architekturübersicht
• Die Rahmenbedingungen für die Entwicklung des Systems, z. B. über die Integration und Anbindung von externen Systemen, Kosten, Entwicklungszeit etc.
• Wichtige Architekturentscheidungen
• Technische und fachliche Abläufe sowie das Zusammenwirken verschiedener Komponenten

Agil entwickeln = nicht dokumentieren?

Viele Entwicklungsteams arbeiten mit agilen Methoden. Und das ist gut so. Allerdings nehmen Entwicklungsteams das agile Prinzip "Funktionierende Software ist wichtiger als umfassende Dokumentation" (https://agilemanifesto.org/) häufig zum Anlass, die Dokumentationsarbeiten noch weiter zurückzuschrauben. Das ist ein Missverständnis. Das agile Prinzip bedeutet nicht, dass keine Dokumentation geschrieben werden muss. Die Dokumentation soll sich nur auf das Wesentliche und Notwendige beschränken. So sollen zum Beispiel lange Spezifikationen vor der eigentlichen Entwicklung vermieden werden. Doch in der Praxis sieht das häufig so aus:

• Es wird nur entwickelt, nicht dokumentiert.
• Die Dokumentation ist nicht Teil der Iteration und nicht Bestandteil der Definition of Done.
• Code wird dokumentiert, aber keine Konzepte.

Folgen von ungenügender Dokumentation

Die aufgeführten Probleme führen nicht nur dazu, dass weniger dokumentiert wird. Die entstehende Dokumentation ist oft auch ungeeignet für die Erweiterung und Wartung der Software. Das heißt unter anderem:

• Es gibt keine Dokumentation, die die Einarbeitung neuer Mitarbeiter durch erfahrene Teammitglieder unterstützt.
• Verlässt ein tragendes Teammitglied die Entwicklung und hat es sein Wissen zu der Systemarchitektur oder den Implementierungsdetails nicht dokumentiert, ist dieses Wissen für das Team verloren.
• Die Erweiterung des Systems um neue Funktionen und seine Wartung werden aufwändiger. Bei jeder Veränderung muss recherchiert werden, wie Komponenten zusammenwirken und Schnittstellen funktionieren.
• Die Auswirkungen von Änderungen an der Software können schlechter bewertet werden, weil nicht sofort klar ist, welche Komponenten betroffen sind.

In vier Schritten zu guter Entwicklerdokumentation

Was ist nun erforderlich, um ein Softwaresystem gleichzeitig ausreichend und mit möglichst geringem Aufwand zu dokumentieren? Wir schlagen die folgenden vier Schritte vor:

1. Zielgruppen der Dokumentation definieren
2. Dokumentationsformen und -methoden definieren
3. Interdisziplinäres Dokumentationsteam bilden
4. Getrennt schreiben, gemeinsam veröffentlichen: mit dem richtigen Tool

Schritt 1: Zielgruppen der Dokumentation definieren

Zunächst müssen wir wissen, wer die Dokumentation liest. Kennen wir die Leser unserer Dokumentation, können wir Inhalte und Formen der Dokumentation ausarbeiten. Und wir schreiben nur wirklich benötigte Dokumentation.

In diesem Artikel betrachten wir folgende Zielgruppen: Entwickler, Architekten und Tester.

Entwickler und Architekten

Für Entwickler, die ein Framework benutzen oder ein bestehendes System pflegen sollen, können unter anderem folgende Informationen von Bedeutung sein:

• Anforderungen und Funktionalitäten des Systems
• Anwendungsfälle der Benutzer (wann wird das System unter welchen Bedingungen wofür eingesetzt)
• Architektur der Software (Systeme, Komponenten, Schichten)
• Technische Konzepte, z. B. Transaktionssicherheit, Skalierbarkeit, Sicherheit gegen unerlaubte Zugriffe, Lizenzverwaltung
• Dokumentation der Schnittstellen
• Klassen- und Methodenreferenz
• Design-Entscheidungen (warum ist das System so wie es ist), Randbedingungen für die Entwicklung

Tester

Tester, die das System und spätere Erweiterungen und Änderungen testen müssen, haben ähnliche Anforderungen wie Entwickler. Darüber hinaus benötigen sie:

• Dokumentation der Testfälle
• Dokumentation der Architektur des Testsystems

Schritt 2: Dokumentationsformen und –methoden definieren

Nicht alle Informationen, die ein Entwickler benötigt, können in einem Dokument zusammengefasst werden. Deswegen ist es sinnvoll, die Entwicklerdokumentation in verschiedene Dokumente aufzuteilen. Doch bevor wir daran gehen, müssen wir folgendes wissen:

• Wer liest was (Personas).
• Was wird wann gelesen (Anwendungskontext).
• Wie häufig wird eine Dokumentation geändert (Änderungshäufigkeit).

Wer liest was (Personas)

Die Leser einer Entwicklerdokumentation teilen wir in drei Lern- und Lesetypen (Personas) ein:

1. Entwickler, die sofort losprogrammieren
Sie lesen Code-Kommentare und verwenden Beispielcode oder existierenden Code als Vorlage.

2. Entwickler, die zunächst die Grundlagen lesen
Sie lesen Architekturdokumentation und technische Konzepte.

3. Entwickler, die bei Bedarf lesen
Sie lesen über einen bestimmten Anwendungsfall (wie löse ich dieses Problem?), suchen themenorientiert nach Use-Case-Beschreibungen und Beispielcode.

Anna gehört zum Typ 2. Sie liest zunächst die Architekturdokumentation und die technischen Konzepte, bevor sie ein Framework benutzt. Später greift sie auf Use Cases zurück oder liest Code-Kommentare, falls erforderlich.

Was wird wann gelesen (Anwendungskontext)

Wir unterscheiden zwischen Informationen, die im jeweiligen Kontext verfügbar sein müssen und Informationen, die der Anwender außerhalb des Entwicklungskontextes und sequenziell lesen kann. Beispiele sind:

• Methoden- und Klassenreferenzen (Code-Kommentare). Sie müssen direkt und kontextsensitiv in der IDE (Entwicklungsumgebung) verfügbar sein.
• Technische Konzepte und Architekturdokumentation. Sie können auch außerhalb der Entwicklungsumgebung und sequenziell wie ein Dokument gelesen werden.

Wie häufig wird die Dokumentation geändert

Wie oft eine Dokumentation geändert werden muss, hängt von ihrer Art ab:

• Architekturbeschreibungen und technische Konzepte werden schwerpunktmäßig entwicklungsbegleitend erstellt und ändern sich daher in späteren Entwicklungsphasen und in der Wartungsphase selten.
• Anwendungsfälle, Szenarien und Beispielcode werden häufiger geändert. Sie müssen jedoch so aufgebaut sein, dass sie leicht erweiterbar sind, für den Fall, dass neue Funktionen und Anwendungsfälle hinzukommen.
• Klassen- und Methodenreferenzen (wenn es sich nicht um veröffentlichte API-Schnittstellen handelt) ändern sich am häufigsten und sollten in Form von Code-Kommentaren geschrieben werden.

Formen von Entwicklerdokumentation

Entsprechend den Zielgruppen, dem Nutzungskontext und der Änderungshäufigkeit kann Entwicklerdokumentation in verschiedenen Formen zur Verfügung gestellt werden:

• Architekturdokumentation
• Developer Guides
• Klassen-/Methodenreferenz

Je nach Anforderungen und Arbeitsprozessen des Unternehmens müssen nicht alle Dokumentationsformen erstellt werden. Denn Dokumentation ist aufwändig, ihre Erstellung und Pflege teuer. Deshalb ist es umso wichtiger, nur die Dokumentationsformen und –mengen zu erstellen, die die Zielgruppen tatsächlich brauchen.

Architekturdokumentation

Diese Form der Dokumentation beschreibt den Aufbau des Systems und fasst die Architekturentscheidungen zusammen, die bei der Entwicklung des Systems und der Grundstruktur des Systems getroffen wurden. Sie wird eher selten geändert und kann außerhalb der Entwicklungsumgebung gelesen werden. Zu den möglichen Inhalten von Architekturdokumentation gehören:

• Überblick über die Software
• Festlegung von zentralen Begriffen (Glossar)
• Zielsetzung der Software
• Rahmenbedingungen
• Qualitätsmerkmale
• Stakeholders und Personas
• Risiken
• Designentscheidungen
• Übergreifende technische Konzepte
• Verschiedene Sichten auf die Architektur (Subsysteme und Komponenten, Sequenzdiagramme etc.)
• Informationen zu Deployment und Betrieb

Eine gute Standardstruktur für Architekturdokumentation finden Sie z. B. auf https://arc42.de/ sowie in dem Buch „Softwarearchitekturen dokumentieren und kommunizieren“ von Stefan Zörner (swadok.de).

Developer Guides/API Guides

Diese Dokumentationsform beschreibt Anwendungsfälle, Problemlösungen und allgemeine Aufgaben bei der Entwicklung von Modulen für eine Softwaresystem. Sie sollte so aufgebaut sein, dass sie einfach erweiterbar ist, falls sich am System etwas ändert. Mögliche Inhalte von Developer Guides sind:

• Beschreibungen zur Implementierung bestimmter Anwendungsfälle oder Abläufe mithilfe der vorhandenen Schnittstellen. Diese sind u. a. für Entwickler nützlich, die zwar den Anwendungsfall kennen, aber nicht die richtige Schnittstelle oder Klasse, um den Fall zu lösen
• Beschreibungen, wie ein bestimmtes Problem gelöst werden soll
• Grundlagen für die Erweiterung und Änderung des Systems
• Beschreibungen allgemeiner Aufgaben wie Event-Handling, Protokollierung, Lokalisierung oder Rechteverwaltung
• Beispielprogramme, Beispielcode und Verweise auf die Referenzdokumentation

Klassen/Methodenreferenz

Diese Dokumentationsformen beschreiben die Schnittstellen, Klassen und Methoden der Software. Sie ist leicht änderbar und kann in die IDE eingebunden werden. Eine Referenzdokumentation enthält:

• Detaillierte Dokumentationen der Schnittstellen, Klassen, Methoden in Form von Code-Kommentaren
• Verweise auf Developer Guide und Architekturdokumentation

Alle diese Dokumentationsformen greifen ineinander. Zwar sollten ihre Inhalte getrennt werden, aber sie sollten sich ergänzen und sich nicht widersprechen. Das funktioniert nur, wenn die Dokumentationsformen als Gesamtheit betrachtet und gepflegt werden, nicht als getrennte Dokumente.

Dokumentationsformen als Gesamtheit

Dokumentationsinhalte, die dieselben Themen behandeln, jedoch in unterschiedlichen Dokumentationsformen angesiedelt sind, sollten miteinander verknüpft werden. Nur so haben die Leser Zugriff auf alle relevanten Informationen zu einem Thema. Idealerweise stehen alle Dokumentationsformen auf einer Plattform zur Verfügung und sind über eine Volltext- und semantische Suche erschließbar.

Schritt 3: Interdisziplinäres Dokumentationsteam bilden

Ein Softwaresystem sollte nicht allein von Entwicklern dokumentiert werden. Auch Technische Redakteure alleine sind keine Alternative, denn sie kennen in der Regel nicht alle Implementierungsdetails und Designentscheidungen und haben nicht zwangsläufig einen technischen Background.

Eine gute Entwicklerdokumentation entsteht in einem interdisziplinären Team, das von den Stärken der verschiedenen Mitglieder profitiert

Produktmanager kennen die Anforderungen und Anwendungssituationen des Systems und die Rahmenbedingungen, die die Entwicklung kennzeichnen. Häufig sind sie diejenigen, die Anforderungen in Form von User Stories aufschreiben und das beste Bild vom Endanwender haben.

Entwickler/Architekten kennen die Designentscheidungen und die Details der Systemarchitektur. Sie wissen, welche Informationen ein Entwickler benötigt, um sich in das System einzuarbeiten, es zu pflegen und zu erweitern. Sie sind mit der Programmiersprache, Entwicklungsumgebung und den Buildprozessen bzw. dem Deployment vertraut.

Technische Redakteure können Dokumentation strukturieren, Zielgruppen analysieren, Wissen aus Köpfen herausholen, eine modulübergreifende Sicht einnehmen und die typischen Benutzeraufgaben aus der Endanwenderdokumentation für die Entwicklerdokumentation nutzbar machen. Außerdem verfügen sie über die notwendigen sprachlichen und didaktischen Fähigkeiten.

Bündelt man diese Kompetenzen, kann eine nützliche Dokumentation entstehen, mit der Softwaresysteme einfach gewartet und erweitert werden können. Denn häufig wird vergessen: In der Regel ist die Wartungszeit um ein Vielfaches länger als die Entwicklungszeit.

Schritt 4: Getrennt schreiben, gemeinsam veröffentlichen – mit den richtigen Tools

Verschiedene Dokumentationsformen werden mit verschiedenen Tools geschrieben. Häufig wird organisatorisch zwischen Entwickler- und Anwenderdokumentation unterschieden, und es werden keine interdisziplinären Dokumentationsteams gebildet. Die Gefahr dabei: Die Dokumentationsformen laufen auseinander.

Tools für Entwicklerdokumentation

• UML-Werkzeuge
• IDE für Code-Kommentare
• Wiki-Artikel

Tools für Anwenderdokumentation

• XML-Editoren oder Redaktionssysteme für XML-basierte Dokumentation
• Layoutprogramme wie FrameMaker oder InDesign

Die gemeinsame Basis

Um ein Software-System im Team zu dokumentieren, sollten Tools und Dokumentation folgende Anforderungen erfüllen:

• Versionierung der Dokumentation und Dokumentationsmodule
• Modularer Aufbau der Dokumentation
• Online-Verfügbarkeit
• Funktionen zum gemeinsamen Schreiben (Kollaboration) und zur Benutzerverwaltung
• Einbinden von Code-Kommentaren und UML-Diagrammen

XML-basierte Dokumentationslösungen erfüllen viele dieser Anforderungen. XML-gestützte Dokumentation kann versioniert und modularisiert werden, und über XSLT können Online-Formate wie HTML oder WebHelp erzeugt werden.

Auch Wikis werden für das gemeinsame Schreiben von Dokumentation verwendet. Sie eignen sich hervorragend für interdisziplinäres Arbeiten.

Allerdings erfüllen XML-basierte Dokumentationslösungen und Wikis nicht alle Anforderungen gleich gut. Häufig benötigen sie weitere Anpassungen. Die Integration von UML-Diagrammen, die Verzahnung von Architekturdokumentation und Code-Kommentaren sowie die Versionierung stellen oft Probleme dar, die im Einzelfall gelöst werden müssen. Ideal ist es, wenn die Dokumentation letztendlich auf einer gemeinsamen Plattform publiziert wird - das kann z.B. eine interne Website oder ein Wiki sein. So ist sichergestellt, dass die Leser alles an einem Platz finden.

Fazit

Fassen wir zusammen. Was macht eine gute Entwicklerdokumentation aus:

• Sie ist konsistent und vollständig und beinhaltet keine Überschneidungen oder veralteten Inhalte.
• Sie ist modular, themenorientiert, bietet Verknüpfungen zwischen verwandten Themen und eine Suche über Volltext oder Metadaten.
• Sie enthält alle erforderlichen Dokumentationsformen, wie z.B. Architekturdokumentation, Developer Guide und Code-Kommentare.
• Sie ist passend für ihre Zielgruppen.
• Sie berücksichtigt die Anforderungen der Anwender des Software-Systems.
• Sie wird erstellt von einem interdisziplinären Dokumentationsteam.
• Sie wird mit Tools erstellt, die zum getrennten Schreiben und gemeinsamen Veröffentlichen geeignet sind.

Eine Entwicklerin wie Anna wird die Qualität eines API oder eines Frameworks auch daran messen, wie gut es dokumentiert ist. Benötigt sie mehr Zeit für die Einarbeitung, kann sie ihre Arbeitsaufgaben nicht schnell genug schaffen. Eventuell unterlaufen ihr auch Fehler, die die Qualität des Produkts beeinträchtigen. Ein gut dokumentiertes API oder Framework dagegen beschleunigt die Einarbeitungszeit und erhöht die Qualität.

Weitere Links

• Documentation for Software Engineers
• Standardstruktur für Architekturdokumentation: https://arc42.de/
• What's an API writer – Wikipedia

Quellen

• Documentation for Software Engineers
• https://agilemanifesto.org/
• https://arc42.de/
• swadok.de
• Wikipedia