12 Dokumentation in der Software-Entwicklung

1. 12 Dokumentation in der Software-Entwicklung • 12.1 Begriff und Einordnung • 12.2 Ziele und Wirtschaftlichkeit der Dokumentation • 12.3 Taxonomie der Dokumente • 12.4 Die Benutzungsdokumentation • 12.5 Die Qualität der Dokumente • 12.6 Die Form der Dokumente, Normen • 12.7 Dokumentation in der Praxis • 12.8 Die gefälschte Entstehungsgeschichte

2. Dokumentieren • Die Dokumentation gilt als ewiges Sorgenkind der Software-Entwicklung. • Dokumentieren ist eine Daueraufgabe. • Nachträgliche Dokumentation ist eine unzureichende Notlösung, denn die Information, die es aufzuzeichnen gilt, ist vergessen oder – mit der Person, die diese Information im Kopf hatte – verschwunden. • Dokumentation tritt demnach im Software-Lebenslauf nicht als eigene Tätigkeit auf. • Software-Entwickeln ist Dokumentieren!

3. 12.1 Begriff und Einordnung

4. Begriffe • Integrierte Dokumentation • Im Programm enthaltene Kommentare, Bezeichner, das Layout. • Separate Dokumentation • Der Teil der Software, der nicht in den Programmen enthalten ist. • Dokumentation • integrierte + separate Dokumentation • Dokument • Jeder Teil einer Dokumentation, der separat erstellt, verwaltet und benutzt werden kann (auch der Code). • Die Form der Dokumente ist damit nicht festgelegt, einzig Stabilität ist unbedingt gefordert: Dokumentation im Kopf gibt es nicht!

5. Integrierte Dokumentation • Integrierte Dokumentation ist leichter zu bearbeiten und hat bessere Chancen, nachgeführt zu werden. • Sie reicht aber in keinem Falle aus! • Bei einem systematischen Vorgehen sind mindestens • 40 % des Aufwands geleistet und damit logisch auch • 40 % der Software entstanden, bevor Code geschrieben wird. • Begriffslexikon, Spezifikation und Architektur-Entwurf müssen unbedingt vorher entstehen! • Sie können nicht in Code-Komponenten abgelegt werden (von der Projektdokumentation ganz zu schweigen).

6. Separate Dokumentation • Die separate Dokumentation ist grundsätzlich gefährdet, sie kann nur funktionieren, wenn • die Anforderungen an die Dokumente und die Verantwortlichkeiten für das Erstellen, Prüfen und Freigeben klar sind, • Dokumentation hoch bewertet und anerkannt wird, • das Inhaltsverzeichnis (die Struktur) der Dokumente zu Beginn festgelegt ist, • Werkzeugunterstützung verfügbar ist, • jedes Dokument nach Fertigstellung und nach Änderungen geprüft wird und • alle Dokumente einer effektiven Konfigurationsverwaltung unterstellt werden.

7. 12.2 Ziele und Wirtschaftlichkeit der Dokumentation

8. Ziele einer guten Dokumentation • Dokumente sind ein Mittel zum Know-how-Transfer und auch zur Kommunikation zwischen Auftraggeber und Auftragnehmer. • In Dokumenten retten und bewahren wir das Wissen über Programme, für die Entwicklung und für die Wartung. • Dokumente erlauben systematische Prüfungen (z. B. Reviews). • Anhand der Dokumente kann man den Projektfortschritt fest-stellen. Ob ein Testbericht vorliegt, lässt sich einfach überprüfen. • Dokumente können die systematische, sorgfältige Entwicklung belegen, sie machen die Software revisionsfest. • Leider ist der Nutzen der Dokumentation verteilt und zeitlich fern, die Kosten treten sofort auf und sind gut sichtbar. • Darum wird an der Dokumentation gespart, gegen die Vernunft. • Wir brauchen mehr und bessere Metriken!

9. Faustformeln für die Kosten • Die durchschnittliche Produktivität beträgt vier Seiten pro Tag. • Ein Personentag kostet 1000 €. • Ein 40 Seiten starkes Dokument kostet demnach etwa 10 000 €. • Dabei ist die Produktivität eher hoch geschätzt! • Aber: • Dokumentation hilft, Fehler zu vermeiden oder sie wenigstens rasch zu finden. • Gut dokumentierte Software lässt sich einfacher erweitern und wiederverwenden.

10. 12.3 Taxonomie der Dokumente

11. Taxonomie • Alle Dokumente gehören zu einer der folgenden vier Kategorien: • SystemdokumentationHierzu zählen alle Dokumente, die für die Konstruktion, den Betrieb und die Wartung der Software benötigt werden. • ProjektdokumentationIn diese Kategorie fallen alle Dokumente, die benötigt werden, um das Entwicklungsprojekt zu planen, zu leiten und abzuschließen. • QualitätsdokumentationDies sind alle Dokumente, in denen die Maßnahmen zur analytischen Qualitätssicherung dokumentiert sind. • Prozessdokumentationbeschreibt den Entwicklungsprozess und seine konkrete Umsetzung im Projekt.

12. Nutzen der Taxonomie • Diese Taxonomie beantwortet die folgenden Fragen: • Welchem Zweck dient das Dokument?Damit auch: Was gehört hinein, was nicht? • Wer wird es lesen, verwenden? (Darstellungsform, Terminologie) • Muss (darf) das Dokument nachgeführt, aktualisiert werden? • Wie lange muss das Dokument verfügbar bleiben? • Fragen der Konfigurationsverwaltung: • Wo und unter welcher Bezeichnung wird es aufbewahrt? • Wer hat auf das Dokument (keinen) lesenden Zugriff? • Wer hat (keinen) schreibenden Zugriff? • Wessen Aufgabe ist die Prüfung und die Abnahme des Dokuments?

13. Kategorien im Überblick

14. 12.4 Die Benutzungsdokumentation

15. Definition und Anforderungen • Damit Software eingesetzt werden kann, muss dokumentiert sein, wie sie installiert, betrieben und bedient wird. • Diese Informationen werden zusammenfassend als Benutzungsdokumentation bezeichnet. • z.B. Benutzungshandbuch, Tutorial, Installationshandbuch, kontextsensitive Hilfe, Online-Informationen • Die Norm ISO/IEC 25051 (2006) definiert folgende Anforderungen an Produkt- und Benutzungsdokumentation für Software: • vollständig • korrekt • genau • in sich konsistent • verständlich

16. Adressaten der Dokumente • Dokumente werden für verschiedene Adressaten erstellt, die sehr unterschiedliche Informationen benötigen.

17. 12.5 Die Qualität der Dokumente

18. Eigenschaften guter Dokumente • Das Ziel der Dokumentation muss es darum sein, brauchbare Dokumente zu erstellen. • Dabei sollten wir die Eigenschaften perfekter Dokumente anstreben. • Das Folgende sollte für alle Dokumente gelten: • Dokumente sind Verfassern und Prüfern zugeordnet. • Dokumente sind zweckmäßig strukturiert und geordnet. • Dokumente haben eine definierte Semantik. • Dokumente liegen in elektronischer Form vor. • Dokumente sind der Konfigurationsverwaltung unterstellt. • Dokumente sind untereinander voll verzeigert.

19. 12.6 Die Form der Dokumente, Normen

20. Normen • Damit Dokumente übersichtlich, leicht zu durchsuchen und zu bearbeiten sind, sollten sie einem vorgegebenen Schema folgen. • IEEE Std 1058 (1998) »Std for Software Project Management Plans« • IEEE Std 1063 (2001) »Std for Software User Documentation« • Die relativ alten DIN 66230 (Programmdokumentation), 66231 (Programmentwicklungsdokumentation), 66232 (Datendokumentation) und 66270 (Bewerten von Softwaredokumenten) • ISO/IEC 6592 (2000) »Leitfaden für die Dokumentation von computergestützten Anwendungssystemen« • ISO/IEC 18019 (2004) »Richtlinien für die Gestaltung und Vorbereitung von Benutzerdokumentation für Anwendungssoftware«

21. 12.7 Dokumentation in der Praxis

22. Folgen schlechter Dokumentation • In der Praxis gehört die Dokumentation meist zu den Problemzonen des Software Engineerings. Warum ist das so? • Software-Entwickler haben Dokumentieren weder in der Ausbildung noch in der Praxis gelernt, sie können es nicht. • Auf Priorität 1 steht die Einhaltung des Liefertermins, auf Priorität 2 und 3 auch. Da die Termine in fast allen Projekten so vorgegeben sind, wird nicht dokumentiert. Dazu fehlt einfach die Zeit. • Folgen: • Wartungsingenieure arbeiten als Archäologen. • Grundlagen für die Handbücher fehlen. • Retrospektive Analysen sind nicht möglich. Damit hat die Organisation keine Möglichkeit, aus dem Projekt zu lernen.

23. 12.8 Die gefälschteEntstehungsgeschichte

24. Motivation und Ziel • Parnas und Clements (1986): A rational design process – how and why to fake it. • Sie fordern, am Ende der Entwicklung (der frühen Phasen) den Weg so zu beschreiben, als sei er rational verlaufen. Denn der Leser hat keinen Vorteil davon, unsere Irrwege zu sehen. • Wir schreiben also, als ob wir schon zu Beginn gewusst hätten, was wir erst am Ende verstanden haben. • Es geht nicht darum, den Leser zu betrügen, sondern ihm Überlegungen zu ersparen, die sich als fruchtlos erwiesen haben. • Die Dokumentation ist kein Protokoll der Entwicklung, sondern eine Hilfe zum Verständnis der Programme. • Achtung: Dieses Konzept gilt nicht für die Projektdokumentation und soll auch nicht dazu führen, dass Fehlentscheide später als richtig dargestellt werden!