This document is posted to help you gain knowledge. Please leave a comment to let me know what you think about it! Share it to your friends and learn new things together.
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 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!