Software Engineering

© Ludewig, J., H. Lichter: Software Engineering – Grundlagen, Menschen, Prozesse, Techniken. 2. Aufl., dpunkt.verlag, 2010.

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

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!

2

12.1Begriff und Einordnung

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!

4

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).

5

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.

6

12.2 Ziele und Wirtschaftlichkeit der Dokumentation

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!

8

Faustformeln für die Kosten

1. Die durchschnittliche Produktivität beträgt vier Seiten pro Tag.

2. 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.

9

12.3Taxonomie der Dokumente

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.

11

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?

12

Kategorien im Überblick

13

Dokumenten-kategorie

Zweck Adressaten Aktuali-sierung

Aufbewahrungsfrist

System-dokumen-tation

Erhaltung und Transfer des Know-hows, Einsatz des Systems

Entwickler, Wartungsinge-nieure, Tester, Kunden

erforderlich bis Ende der Systemnutzung

Projekt-dokumen-tation

Führung des Projekts, Analyse nach Projektende

Linien- und -Projektmanager, Kunden

unerwünscht bis Projektende plus n Jahre

Qualitäts-dokumen-tation

Nachweis der Maßnahmen zur Qualitätssicherung

Linien- und -Projektmanager, Kunden

verboten bis Ende der Systemnutzung

Prozess-dokumen-tation

Beschreibung der Vorgehensweise, Unterstützung bei der Durchführung

alle, die aktiv am Projekt beteiligt sind

sinnvoll bis Ende der Systemnutzung und so lange, wie der Hersteller existiert

12.4 Die Benutzungsdokumentation

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

15

Adressaten der Dokumente

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

16

Adressat Zweck Dokumente

Käufer Kaufentscheidung treffenLeistet die Software das, was ich benötige?

Produktbeschreibung

Administrator Installation der SoftwareWie wird die Software installiert und deinstalliert?

Installationsanweisung

Betrieb der SoftwareWas muss ich wissen, um die Software nach der Installation zu betreiben?

AdministrationshandbuchRelease-Notes

UnerfahrenerAnwender

Bedienung kennenlernenWie kann ich die Software starten und die wichtigsten Funktionen ausführen?

Erste-Schritte-DokumentTutorial

ErfahrenerAnwender

NachschlagenWelche Funktionen und Einstellungen kann ich im Detail durchführen?Was tue ich, wenn ein Fehler auftritt?

BenutzungshandbuchFAQ-Liste

12.5Die Qualität der Dokumente

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.

18

12.6 Die Form der Dokumente, Normen

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«

20

12.7Dokumentation in der Praxis

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.

22

12.8 Die gefälschte Entstehungsgeschichte

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!

24