Transcript No Slide Title

Software Engineering
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
© Ludewig, J., H. Lichter: Software Engineering – Grundlagen, Menschen, Prozesse, Techniken. 2. Aufl., dpunkt.verlag, 2010.
Dokumentieren
Die Dokumentation gilt als ewiges Sorgenkind der SoftwareEntwicklung.
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.1 Begriff 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 feststellen. 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.3 Taxonomie der Dokumente
Taxonomie
Alle Dokumente gehören zu einer der folgenden vier Kategorien:
● Systemdokumentation
Hierzu zählen alle Dokumente, die für die Konstruktion, den
Betrieb und die Wartung der Software benötigt werden.
● Projektdokumentation
In diese Kategorie fallen alle Dokumente, die benötigt werden, um
das Entwicklungsprojekt zu planen, zu leiten und abzuschließen.
● Qualitätsdokumentation
Dies sind alle Dokumente, in denen die Maßnahmen zur
analytischen Qualitätssicherung dokumentiert sind.
● Prozessdokumentation
beschreibt 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
Dokumentenkategorie
Zweck
Adressaten
Aktualisierung
Aufbewahrungsfrist
Systemdokumentation
Erhaltung und Transfer
des Know-hows, Einsatz
des Systems
Entwickler,
Wartungsingenieure, Tester,
Kunden
erforderlich
bis Ende der
Systemnutzung
Projektdokumentation
Führung des Projekts,
Analyse nach
Projektende
Linien- und Projektmanager,
Kunden
unerwünscht
bis Projektende
plus n Jahre
Qualitätsdokumentation
Nachweis der
Maßnahmen zur
Qualitätssicherung
Linien- und Projektmanager,
Kunden
verboten
bis Ende der
Systemnutzung
Prozessdokumentation
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
13
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.
Adressat
Zweck
Dokumente
Käufer
Kaufentscheidung treffen
Leistet die Software das, was ich benötige?
Produktbeschreibung
Administrator
Installation der Software
Wie wird die Software installiert und
deinstalliert?
Installationsanweisung
Betrieb der Software
Was muss ich wissen, um die Software nach der
Installation zu betreiben?
Administrationshandbuch
Release-Notes
Unerfahrener
Anwender
Bedienung kennenlernen
Wie kann ich die Software starten und die wichtigsten
Funktionen ausführen?
Erste-Schritte-Dokument
Tutorial
Erfahrener
Anwender
Nachschlagen
Welche Funktionen und Einstellungen kann ich im Detail
durchführen?
Was tue ich, wenn ein Fehler auftritt?
Benutzungshandbuch
FAQ-Liste
16
12.5 Die 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.7 Dokumentation 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