10 Dokumentation - Universität Stuttgart

Softwaretechnik I 

ST I 

§ 10 Dokumentation 

Lernziele 

– Verstehen, wozu man die Dokumentation braucht 

– Wissen, was eine gute Dokumentation beinhaltet 

– Erklären können, was der Unterschied zwischen den unterschiedlichen 

Dokumentationsarten ist 

– Erklären können, was der Begriff Dokumentationsmanagement bedeutet 

© 2013 IAS, Universität Stuttgart 445


ST I 


10.1 Zweck und Inhalt der Dokumentation 

10.2 Benutzungsdokumentation 

10.3 Systemdokumentation 

10.4 Projektdokumentation 

10.5 Dokumentationsmanagement 

10.6 Zusammenfassung 



ST I 

Dokumentation und ihre Grenzen 

Handtücher 

Herunterziehen 

und abreißen 

Handtücher 



ST I 

Warum braucht man Dokumentation? 

– Anteil der Wartung an den Entwicklungskosten 

Wartungskosten 

40-60% 

70-80% 

90% 

80er Jahre 

90er Jahre 

Ende der 90er Jahre 

– Gründe für die Dokumentation: 

• Entwicklerunterstützung 

• Installationsunterstützung 

• Benutzungsunterstützung 

• Testunterstützung 

• Projektmanagementunterstützung 

unterschiedliche Ziele 

unterschiedliche Dokumente 



ST I 

Klassen von Dokumentation nach Nutzergruppen 

– Benutzungsdokumentation 

Benutzer des Softwareprodukts 

– Systemdokumentation 

Entwickler des Softwareprodukts 

Personen, die mit den Änderungen und Erweiterungen beschäftigt sind 

– Projektdokumentation 

Manager des Softwareprojekts 

Ziel der Dokumentation während des Produkt-Lifecycles 

- Während der Entwicklung: Kommunikation zwischen den an der Entwicklung 

beteiligten Personen 

- Nach der Entwicklung: Unterstützung des Einsatzes und der Wartung 

von Softwareprodukten 

- Zukünftige Projekte: Dokumentation des Projektverlaufs zur 

Kalkulation der Herstellungskosten und zur 

besseren Planung neuer Produkte 



ST I 

Dokumentationsarten 

mitgelieferte Dokumentation 

– gedruckte Dokumentation 

– elektronische Dokumentation 

PDF oder HTML-Dokumente 

Online-Hilfe (kontextsensitiv) 

Assistenten 

Multimedia 

Web-basierte Dokumentation (Produkt- oder Projektportal) 

Alle Arten von elektronischer Dokumentation plus 

– Diskussionsgruppen (Newsgroups/Webforen) 

Dokumentation 

– FAQs / HowTos 

– Newsletter 

– Downloadbereich 

Kommunikation 



ST I 

Gedruckte Benutzungsanleitung 



ST I 

Benutzungsanleitung als PDF-Dokument 



ST I 

Benutzungsanleitung als Online-Hilfe 



ST I 

Web-basierte Benutzungsanleitung 



ST I 

Nutzen von Multimedia bei Benutzungsdokumentation 

Hilfeassistent 

Audio-Clips 

„Guided tours“ 

„Screenmovies“ 



ST I 

Diskussionsgruppen (Foren) (1) 

Liste von Einträgen zu einem speziellen Thema 



ST I 

Diskussionsgruppen (Foren) (2) 

Problembeschreibung und dazugehörige Antwort 



ST I 

Frequently Asked Questions (FAQ) (1) 

Liste von Fragen nach Themengebiet sortiert 



ST I 

Frequently Asked Questions (FAQ) (2) 

Antworten zu speziellen Fragen 



ST I 

Newsletter 

Informationen über neuste Technologien, Produkte, Werkzeuge, ... per E-Mail 


Fragen zur Vorlesung 

ST I 

Frage zu § 10.1 

Welchen Aussagen stimmen Sie zu? 

f 

Die Dokumentation erfolgt nur während der Entwicklung zur Unterstützung 

der Softwareerstellung 

f Die Dokumentation beschreibt nur das System 

 

Diskussionsforen können auch zum fachlichen Austausch genutzt werden 

 

Mit Hilfe von Multimedia lässt sich die Benutzungsdokumentation 

verbessern 



ST I 










ST I 

Inhalt der Benutzungsdokumentation 

– Allgemeine Systembeschreibung für Anwender 

– Installations- und Benutzungsanleitung 

– Tutorials 

– Hilfe / Troubleshooting 

Allgemeine Systembeschreibung für Anwender 

– Charakterisierung der Funktionalität und der Systemgrenzen 

– Zweck des Softwaresystems 

– Benötigte Hardware- und Softwareressourcen 

– Art und Weise der Benutzer-System-Interaktion 

– Form der produzierten Ergebnisse 

– Organisatorische und informationstechnische Voraussetzungen 



ST I 

Installations- und Benutzungsanleitung 

– Angaben über Durchführung und Voraussetzungen der Installation des 

Softwaresystems (benötigte Dateien, technische Ressourcen) und 

Einbettung in das Betriebssystem 

– Vollständige und leicht verständliche Beschreibung aller Systemfunktionen 

und der für ihre Ausführung notwendigen Benutzungsaktionen 

– Typische Anwendungsbeispiele für alle Systemfunktionen 

– Angaben und Erläuterungen über die Eingabedaten 

– Darstellung und Erläuterung der Ergebnisse anhand von Beispielen 

– Zusammenstellung der Fehlermeldungen und Hinweise auf 

Fehlerursachen und Maßnahmen zur Fehlerbeseitigung 



ST I 

Form der Benutzungsdokumentation 

– Verwende aktive anstelle von passiven Formulierungen 

– Verwende keine langen Sätze, die mehrere verschiedene Tatsachen 

beschreiben 

– Verweise auf vorher gegebene Informationen nicht nur durch Angabe von 

Kapitelnummern, sondern erinnere an Titel und Inhalt des referenzierten 

Abschnitts 

– Nummeriere und tabelliere Aussagen 

– Komplexe Sachverhalte redundant aus verschiedenen Sichten 

beschreiben 

– Einschränkungen in der Weitschweifigkeit, Qualität vor Quantität 

– Definiere präzise alle verwendeten Begriffe 

– Verwende kurze Absätze (bis zu sieben Zeilen) 

– Verwende Haupt- und Unterkapitel 

– Vermeide Schreibfehler und Strukturierungsfehler, Qualität des Produkts 

wird an der Qualität der Dokumentation gemessen 



ST I 

Beispiel für Benutzungsdokumentation 

Überblick über die Dokumentation zu MS XML Parser 3.0 



ST I 


Welchen Aussagen stimmen Sie zu? 

f 

 

Die Qualität der Benutzungsdokumentation entscheidet über die Qualität 

des gesamten Produkts 

 

Die Benutzungsdokumentation unterstützt den Anwender bei der 

Bedienung des Systems 

In der Benutzungsdokumentation werden alle internen 

Systemfunktionen beschrieben. 



ST I 










ST I 

Inhalt der Systemdokumentation 

Beschreibung aller Einzelheiten des Aufbaus eines Softwaresystems, der 

Struktur der einzelnen Module und der Testaktivitäten 

Gliederung der Systemdokumentation 

1) Aufgabenstellung (Systemspezifikation) 

2) Analyseergebnisse 

3) Entwurfsergebnisse 

4) Verwendeten Dateien 

5) Testprotokollierung 

6) Listing aller Programme 



ST I 

Anforderungsdefinition und Analyseergebnisse 

1) Beschreibung der Aufgabenstellung (Anforderungsdefinition) 

– aktualisierte Vertragsgrundlage 

– Beschreibung verwendeter aktueller Prototypen 

2) Analyseergebnisse 

– Konzeption und Grundstruktur des Softwaresystems und seiner 

Module 

– Zerlegung der Gesamtlösung in Teillösungen 

– Definition der Schnittstellen der Module 

– Beschreibung von Schwierigkeiten und Änderungsgründen 



ST I 

Entwurfsergebnisse und Dateibeschreibungen 

3) Entwurfsergebnisse 

– Beschreibung der Module nach einem einheitlichen Schema 

– Sicherstellung der Aktualität der Information 

4) Beschreibung der verwendeten Dateien 

– Dateiname, Dateiinhalt 

– Dateiorganisation 

– maximale Dateigröße 

– Zugriffsrechte und mögliche Zugriffsarten 

– Form der möglichen Lese- und Schreiboperationen 



ST I 

Testprotokollierung 

5) Testprotokollierung 

– Testplan für den Integrations- und den Abnahmetest 

– Testplan für jedes Modul 

– Beschreibung der Testumgebung für jedes Modul und jedes Subsystem 

– Protokollierung der ausgeführten Testfälle 



ST I 

Beispielaufbau einer Modulbeschreibung 

– Name: Name des Moduls 

– Stichwort: Kurze Kennzeichnung der Aufgabe 

– Importschnittstelle: Angabe von Name, Typ und Bedeutung aller importierten 

Operationen und ihrer Zugehörigkeit zu einem Modul 

– Exportschnittstelle: Angabe von Typ und Bedeutung aller exportierten 

Operationen 

– Aufrufe: Aufrufe sämtlicher exportierter Prozeduren mit Parametern 

und Parametertypen, Unterscheidung Eingangs-, Ergebnisund 

Übergangsparameter 

– Aufgabe: Kurze Beschreibung der Aufgaben eines Moduls 

– Datenstrukturen: Eigenschaften der Datenstrukturen aus der Sicht der 

Modulbenutzer 

– Exportierte und innere Prozeduren: 

– Konkrete Datenstruktur: 

Beschreibung der Prozeduren / Algorithmen / des Verhaltens 

im Fehlerfall, Hinweise auf die Behandlung von Sonderfällen 

Konkrete Implementierung von abstrakten Datenstrukturen 

– Modulinitialisierung: Beschreibung von Modulvorbedingungen 



ST I 

Beispielaufbau einer Klassenbeschreibung 

Name: 

Stichwort: 

Name der Klasse 

Kurze Kennzeichnung des Zwecks der Klasse 

Erbenschnittstelle: Beschreibung der Operationen und Attribute, auf die Erben Zugriff 

haben 

Exportschnittstelle: Beschreibung der Operationen und Attribute, auf die Klienten 

Zugriff haben 

Beschreibung von Name, Typ und Bedeutung der Operationen 

und Attributen 

Basisschnittstelle: Beschreibung, von welchen Klassen geerbt wird 

Importschnittstelle: Beschreibung, welche Klassen für die Implementierung benötigt 

werden 

Aufgabe: 

Abstrakte Datenstruktur: 

Beschreibung der Aufgaben der Klasse 

Beschreibung der Eigenschaften der realisierten Datenstruktur 

aus der Sicht des Klassenbenutzers 



ST I 

Form der Systemdokumentation 

– knapp und präzise 

– nicht zu ausführlich 

– Verwendung von Hypertextfunktionalität 

– Verwendung formaler Sprachmittel mit einheitlichen Formalismen 

und Darstellungsformen für alle Beteiligten 

– Erstellung während der Entwicklung 

1) Systemspezifikation in der Spezifikationsphase 

2) Analyseergebnisse in der Analysephase 

3) Entwurfsergebnisse in der Entwurfsphase 

4), 6) Verwendete Dateien und Listings aller Programme 

während der Implementierung 

5) Testprotokollierung in der Spezifikations- und Testphase 

– Abrundung der Dokumentation nach Fertigstellung des Softwareprodukts 



ST I 

Beispiel für Systemdokumentation 

Detaillierte Spezifikation der Schnittstellen 



ST I 


Welche Informationen sollten in der Dokumentation der 

Analyseergebnisse enthalten sein? 

f 

f 

f 

 

Schnittstellendefinitionen 

Detaillierte Modulbeschreibungen 

Definition der Zugriffsrechte auf Dateien 

Beschreibung der Testumgebung für die einzelnen Module 

 

Grundstruktur des Softwaresystems 



ST I 










ST I 

Inhalt der Projektdokumentation 

– Projektplan mit den einzelnen Realisierungsphasen und dem geplanten 

Zeitrahmen 

– Organisationsplan mit Personalzuteilung und Personalführung für die 

einzelnen Realisierungsphasen 

– Angabe über Ergebnisse (Produkte), die nach jeder Realisierungsphase 

vorliegen 

– Definition des Projektstandards mit Festlegung der Entwurfsmethode und 

der Teststrategie, Vorgabe von Konventionen für die Dokumentation 

– Verzeichnis aller zum Projekt gehörenden Dokumente, Informationen über 

den Entwicklungsstand, Zugriffsrechte und die Archivierung 

– Verzeichnis über die verbrauchte Arbeitszeit, Ressourcen und sonstige 

Aufwendungen 

– Projekttagebuch zur Protokollierung der Besprechungen von 

Projektmitarbeitern, Informationen über Entscheidungen mit 

entsprechender Begründung 



ST I 

Projektdokumentation von studentischen Arbeiten (1) 

AISA-Applikation (Aktive Information Studentischer Arbeiten) 

AISA-Werkzeug 

Präsentation auf CD oder im Intranet: 

Große Anzahl an Projektdokumenten: 

– Ergebnisdokumente aus den 

Projektphasen (Planung, Definition, 

Entwurf, Implementierung, Integration) 

– Quellcode und Benutzungsanleitung 

– Projektplan 

– KM-Dokumente 

– Video für Vortrag 

– Lebenslauf des Studenten 

– Vorstellungsvideo 

AISA-Applikation 



ST I 


Ergebnisdokumente der 

Projektphasen 

Projektplanung 



ST I 


Versionen der erstellten 

Dokumente 

Begriffe 



ST I 


Welche Informationen sollten in der Projektdokumentation enthalten sein? 

f 

Schnittstellendefinitionen 

 

Organisationsplan 

 

 

 

Informationen über Entscheidungen 

Protokollierung von Besprechungen 

Angaben über verbrauchte Arbeitszeit 



ST I 










ST I 

Effiziente Dokumentenerstellung 

Erstellung von unterschiedlichen Dokumentationsarten aus einer Quelle 

– Generierung von Online-Hilfen mit Textverarbeitungssystem, das zur 

Erstellung von gedruckten Dokumenten benützt wird. 

– Generierung von Dokumentation aus Kommentaren im Sourcecode 

– Erstellung von Webseiten, die ein Umschalten auf eine druckbare Version 

erlauben 

– Ableiten der Benutzungsdokumentation aus der Anforderungsdefinition 

(z. B. Use Cases) 

– Generierung von verschiedenartiger Dokumentation durch die Benutzung 

eines Informationsmanagementsystem 



ST I 

Beispiel Javadoc (1) 

Dokumentationserstellung aus kommentiertem Quellcode 

1. Einfügen von Kommentaren in den Quellcode 

Überblick 

package 

Klassen, Interfaces 

Konstanten, Attribute, Methoden 

/** 

* Registers the text to display in a tool tip. The text 

* displays when the cursor lingers over the component. 

* 

* @param text The string to display. If the text is null, 

* the tool tip is turned off for this component. 

*/ 

public void setToolTipText(String text) 

{ 

//... 

} 

2. Ausführen des Javadoc-Tools, welches den Quellcode 

nach Deklarationen und Kommentaren durchsucht 

und HTML-Seiten generiert 



ST I 

Beispiel Javadoc (2) - Resultierende HTML-Dokumentation 

Weitere Informationen: http://java.sun.com/j2se/javadoc/ 



ST I 

Funktionen des Dokumentenmanagements 

– Erfassen/Integrieren 

Übernehmen vom Erstellungssystem, Einspielen, Einscannen 

– Erschließen 

Identifikation und Klassifikation hinzufügen 

– Prüfen/Freigeben 

Vergleich mit Aufgabenstellung 

– Archivieren 

Langfristig speichern, gegen Manipulation schützen 

– Verteilen 

Weiterleiten an Empfänger gemäß Verteilschlüssel, Bestätigen des Empfangs 

– Recherchieren 

Suchen nach diversen Kriterien, Ansehen, Ausdrucken 

– Ändern 

Prüfen Notwendigkeit und Auswirkungen, Generieren und Überwachen 

Änderungsauftrag, Austausch 

– Versenden 

Übermitteln an bestimmten Empfänger, Ausgabe bei Bedarf des aktuell gültigen 

Dokuments 



ST I 

Regeln 

– Keine Aktivität ohne Ergebnisdokument 

– Eine Aktivität ist erst beendet, wenn alle Ergebnisdokumente vorhanden 

und freigegeben sind 

– Für jedes Dokument gibt es einen verantwortlichen Ersteller 

– Alle Informationen, die nicht ausdrücklich vertraulich sind, sind für alle 

Projektbeteiligten frei zugänglich 

– Dokumentationsregeln gelten für interne wie externe Projektbeteiligte 

– Änderungen freigegebener Dokumente sind nur über den Änderungsdienst 

zulässig 

– Jedes Dokument erhält eine eindeutige Kennung und aussagefähige 

Deskriptoren (Nutzung der Erstellungssysteme) 

– Es sind für alle Dokumente Vorlagen verfügbar 



ST I 

Gefahren bei unzureichendem Dokumentationsmanagement 

– Langes Suchen nach benötigten Unterlagen 

– Inkonsistenzen in den Dokumenten 

– Doppelarbeit statt Verwendung der Ergebnisse anderer 

– Beweisnot bei Streitfällen 

– Individuelle Dokumentationsqualität 

– Fehlender Maßstab für den Fertigstellungsgrad und die 

Ergebnisqualität von Projektaktivitäten 

– Aufwand für Aufbereitung von Projektunterlagen als 

Ergebnisdokumentation 

– Aufwand für die Aufbereitung für die Nachnutzer 

– Sukzessives statt simultanes Arbeiten, da Ergebnisse 

anderer fehlen 

– Zeitverluste für Informationsübermittlung 



ST I 


Welche der folgenden Punkte sind Funktionalitäten eines 

Dokumentenmanagementsystems? 

f 

 

 

Weiterleitung von Dokumenten 

Archivierung von Dokumenten 

 

Recherche im Dokumentbestand 

Erstellung neuer Dokumente 



ST I 










ST I 

Zusammenfassung 

– Die Dokumentation verfolgt unterschiedliche Ziele, deshalb gibt es auch 

unterschiedliche Dokumentationsarten 

– Die Benutzungsdokumentation ist für den Benutzer des Softwareprodukts 

– Die Systemdokumentation wird für die Entwickler des Softwareprodukts 

erstellt. 

– Die Projektdokumentation ist für den Manager des Softwareprojektes 

– Die Dokumentation unterstützt den gesamten Softwareentwicklungsprozess 

einschließlich des Betriebs und der späteren Wartung des 

Softwareprodukts 

– Eine Softwareprodukt ist nur so gut, wie seine Dokumentation 



ST I 

Vorbereitungsfragen zu § 10 

Frage 1: Dokumentation (SS 04) 

Wie können Sie Programmierer dazu bewegen, ihre Software bereits während der 

Entwicklung zu dokumentieren? 

Hinweis: Nennen Sie ausschließlich Maßnahmen positiver Motivation (keine monetären 

Maßnahmen, o. Ä.). Woran arbeiten Programmierer am liebsten? 

Frage 2: Welche Aussagen zur Dokumentation sind richtig? (WS 05/06) 

Informationen und Dokumente dürfen anderen Projektbeteiligten nur zur Verfügung 

gestellt werden, wenn diese ausdrücklich dazu berechtigt sind. 

Die Projektdokumentation enthält ein Verzeichnis über die verbrauchte Arbeitszeit, 

Ressourcen und sonstige Aufwendungen. 

Bei der Dokumentation ist es wichtig, alle notwendigen Informationen in einem 

Dokument zusammenzufassen. 

Bei der Softwareentwicklung spielen Schreibstil und Schreibfehler in einer 

Dokumentation nur eine untergeordnete Rolle.

10 Dokumentation - Universität Stuttgart

Erfolgreiche ePaper selbst erstellen

Template löschen?

Als Template speichern?