Softwaredokumentation

Mit Softwaredokumentation bezeichnet man die Dokumentation von Computer-Software. Sie erklärt für Anwender und Benutzer in unterschiedlichen Rollen, wie die Software funktioniert, was sie erzeugt und verarbeitet (z. B. Daten), wie sie zu benutzen ist, was zu ihrem Betrieb erforderlich ist und auf welchen Grundlagen sie entwickelt wurde.

Arten der Softwaredokumentation

Die vollständige Dokumentation zu einem Softwareprodukt besteht aus unterschiedlichen Teilen, die auf verschiedene Zielgruppen ausgerichtet sind:

• Programmiererdokumentation
  Beschreibung des Quellcodes.
• Methodendokumentation
  Allgemeine Beschreibung der Grundlagen, auf denen die Software beruht. Dies können mathematische Algorithmen, technisch-wissenschaftliche oder kaufmännische Verfahren sein, auf die in den anderen Dokumentationsteilen verwiesen werden kann. Die Software implementiert diese Methoden; die Methodendokumentation nimmt aber keinen Bezug auf technische Details der Programmierung, die sich häufiger ändern können.
• Installationsdokumentation
  Beschreibung der erforderlichen Hardware und Software, mögliche Betriebssysteme und -Versionen, vorausgesetzte Software-Umgebung wie etwa Standardbibliotheken und Laufzeitsysteme.
  Erläuterung der Prozeduren zur Installation, außerdem zur Pflege (Updates) und De-Installation, bei kleinen Produkten eine Readme-Datei.
  Zielgruppe sind Administratoren beim Anwender, die die Software nicht zwangsläufig unmittelbar selbst nutzen müssen.
• Benutzerdokumentation
  Informationsmaterial für die tatsächlichen Endbenutzer, etwa über die Benutzerschnittstelle.
  Den Anwendern kann auch die Methodendokumentation zugänglich gemacht werden, um Hintergrundinformationen und ein allgemeines Verständnis für die Funktionen der Software zu vermitteln.
• Datendokumentation
  Oft sind nähere Beschreibungen zu den Daten erforderlich. Es sind die Interpretation der Informationen in der realen Welt, Formate, Datentypen, Beschränkungen (Wertebereich, Größe) zu benennen.
  Die Datendokumentation kann oft in zwei Bereiche aufgeteilt werden:
  1. Innere Datenstrukturen, wie sie nur für Programmierer sichtbar sind.
  2. Äußere Datendokumentation für solche Datenelemente, die für Anwender sichtbar sind – von Endbenutzern einzugebende und von der Software ausgegebene Informationen.
     Dazu gehört auch die detaillierte Beschreibung möglicher Import-/Exportschnittstellen.
• Testdokumentation
  Nachweis von Testfällen, mit denen die ordnungsgemäße Funktion jeder Version des Produkts getestet werden können, sowie Verfahren und Szenarien, mit denen in der Vergangenheit erfolgreich die Richtigkeit überprüft wurde.
• Entwicklungsdokumentation
  Nachweis der einzelnen Versionen auf Grund von Veränderungen, der jeweils zugrundegelegten Ziele und Anforderungen und der als Vorgaben benutzten Konzepte (z. B. in Lastenheften und Pflichtenheften); beteiligte Personen und Organisationseinheiten; erfolgreiche und erfolglose Entwicklungsrichtungen; Planungs- und Entscheidungsunterlagen etc.

Einige Dokumentationsteile bleiben vertraulich im Bereich der Entwickler, andere müssen für die Anwender verfügbar sein. Teilweise erfüllen sie neben technischen auch juristische Zwecke, als Vertragsbestandteil und im Fall von Gewährleistungsansprüchen.

Zusammenfassend kann die Softwaredokumentation unterschieden werden nach:

• Projektdokumenten: Sie beschreiben, was von den Entwicklungsbeteiligten zu tun ist (bzw. war) - warum (z. B. Ziele, Anforderungen), wie (Methodik), wann (Planungsdokumente), womit (Werkzeuge) etc.
• Systemdokumenten: Sie beschreiben das SYSTEM - woraus es besteht, was es tut (Funktionen), was es erzeugt (Ergebnisse), welche Daten es verarbeitet, wie es zu bedienen ist etc.

Wird diese Unterscheidung bereits im Projektverlauf berücksichtigt, so kann der Aufwand für das Erstellen von Systemdokumenten (die zur Einführung erforderlich sind) weitgehend reduziert werden.

Softwaredokumentation aus juristischer Sicht

Die Rechtswissenschaft betrachtet Software aus einem gänzlich anderen Blickwinkel als die Informatik, nämlich z. B. unter den Aspekten Verbraucherschutz, Haftung und Gewährleistung etc. Softwareprodukte sind hier lediglich eine Variante von 'Produkten' unter vielen anderen Arten. Aus dieser Sicht gehört zu Softwareprodukten auch eine Dokumentation.

Hierzu ein Zitat nach Beckmann ^[1]: „Nach der Rechtsprechung des BGH zum Thema "EDV-Anwenderdokumentationen" ist es als geklärt anzusehen, dass, unabhängig vom in Frage kommenden Vertragstyp, die Softwareüberlassung neben der Überlassung des Programms auch zur Überlassung entsprechender Programminformationen verpflichtet. Dabei ist zu beachten, daß es sich nicht nur um eine im Neben- sondern vielmehr um eine im Gegenseitigkeitsverhältnis stehende Hauptleistungspflicht des Lieferanten handelt, und zwar sowohl bei Standard- als auch bei Individualsoftware.“

Der juristische Sprachgebrauch weicht im übrigen von dem in der anwendenden Industrie ab: Dokumente wie vor allem die Gebrauchsanleitungen zählen hier zu den Instruktionen. Dokumentation im engeren juristischen Sinn umfasst dagegen nur Protokolle und Belege zum Werdegang eines Produktes, also über Entwicklung, Produktion, Prüfung, Auslieferung(sweg); Quelle: ^[2]. Wenn im vorangehenden Absatz von "EDV-Anwenderdokumentationen" gesprochen wird, geht es offensichtlich um eine Gerichtsentscheidung, die sich für einen konkreten Fall an die Wortwahl der Industrie anpasst.

Historische Entwicklung und moderne Formen

Die Art und der Umfang von Softwaredokumentation haben sich seit den 1960er und 1970er Jahren bis heute stark gewandelt.

In Deutschland gab es aus den 1980er Jahren drei Normen auf dem Gebiet „Informationsverarbeitung“, die im Juni 2004 ohne Ersatz zurückgezogen wurden, weil sie nicht mehr zeitgemäß umgesetzt werden konnten:

• DIN 66230 Programmdokumentation
• DIN 66231 Programmentwicklungsdokumentation
• DIN 66232 Datendokumentation

Programmiererdokumentation

Die ersten Anwendungsprogramme wurden auf Lochkarten gestanzt und hatten einen relativ geringen Umfang, also etwa einige Tausend Zeilen. Kommentare im Quellcode waren selten. Die Programmiererdokumentation musste in einem separaten Schriftstück ausführlich und mit Flussdiagrammen Zeile für Zeile die Funktion erläutern.

Dies ist heute nicht mehr möglich. Der Umfang aktueller Softwaresysteme und die Schnelligkeit, mit der von einer Vielzahl von Programmierern Änderungen vorgenommen werden können, lassen das althergebrachte Vorgehen nicht mehr zu.

Moderne Softwaredokumentation verfolgt andere Ansätze:

• Der Quellcode soll selbsterklärend sein.
  Die Namen von Variablen und Funktionen sollen für Menschen intuitiv verständlich sein. Wo sich bereits die formale Programmiersprache selbst ausreichend erklärt und die Struktur durch geeignetes Ein- und Ausrücken von Kontrollstrukturen bereits hinreichend deutlich wird, darf keine zusätzliche und unabhängige Beschreibung angefertigt werden – bei Änderungen des Programms kommt es sofort zu Klaffungen und Inkonsistenzen. Die personellen Ressourcen zur zeitnahen Pflege überflüssiger Dokumente sind regelmäßig nicht vorhanden.
• Die Dokumentation soll soweit wie möglich in den Quellcode eingearbeitet sein.
  Das kann durch Kommentare und Kommentarzeilen erreicht werden, die in unmittelbarer Nähe der Anweisungen im Quellcode stehen und bei deren Veränderung sofort aktualisiert werden können. Bei der Weiterbearbeitung durch andere Programmierer, die weltweit verteilt arbeiten können, steht immer die aktuelle Kommentierung zur Verfügung und kann weiter angepasst werden. Was bereits durch die formale Programmiersprache selbst erklärt wurde, darf nicht Inhalt eines zusätzlichen Kommentars sein.
• Unterstützende Übersichten sollen mit Dokumentationswerkzeugen automatisch aus dem Quellcode und speziell formatierten Kommentaren generiert werden.
  Dienstprogramme wie etwa Javadoc oder Doxygen können komplexe Hypertexte als Referenz erstellen, mit denen sich die Entwickler schnell auch in umfangreichen Systemen zurechtfinden können. Integrierte Entwicklungsumgebungen stellen interaktiv auch grafische Übersichten wie etwa Strukturbäume zusammen. Die Datenstruktur von Objekten kann in Form von Grafiken statisch (auf Papier) und dynamisch (durch interaktive Navigation) verdeutlicht werden.
• Soweit Anmerkungen, Skizzen und dergleichen nicht in den Quellcode selbst integriert werden können, sollen sie als Dateien unmittelbar bei den entsprechenden Dateien des Quellcodes gespeichert und gemeinsam verteilt werden, damit sie allen Entwicklern zur Verfügung stehen und es nicht zu Inkonsistenzen kommt.

Die Programmiererdokumentation im engeren Sinn zielt auf die Programmierung des Quellcodes selbst ab. Neben dieser „inneren“ Dokumentation gibt es oft noch eine nach „außen“ gerichtete Dokumentation, welche sich an andere Programmierer wendet, die eine Programmierschnittstelle nutzen.

Sinnvolle Programmiererdokumentationen werden heute praktisch nur noch in elektronischer Form und nicht mehr als Papierdokumente und Bücher erstellt:

• Die häufigen und vielfältigen Veränderungen lassen gedruckte Werke sofort veralten.
• Elektronische Dokumente können sofort weltweit in der aktuellen Form verfügbar gemacht werden.
• Die Produkte werden so komplex, dass ein Inhaltsverzeichnis oder ein alphabetisches Register nicht ausreicht, um durch das System zu navigieren. Erforderlich sind interaktiv elektronische Hilfsmittel, wie Hyperlinks, Suchfunktionen und dynamisch durch Ein- und Ausblenden wechselnde Ansichten auf die Informationsmenge.

Benutzerdokumentation

Die Benutzerdokumentation dient dazu, dem Benutzer die Anwendung des Programms zu erklären.

Eine gutes Benutzerhandbuch besteht aus:

• Informationen zur Funktion der Software in der Sicht der Problemwelt des Anwenders.
• Eine grundlegende Bedienungsanleitung.
• Ratschläge zur Problembehebung, Fehleranalysen mit Gegenmaßnahmen.
• Ein Tutorial, bei dem die Lösung einiger Übungsaufgaben exemplarisch möglich ist, und im Idealfall eigenständige Lösungsversuche begleitet und bei Misserfolg aufgelöst werden.
• Frequently Asked Questions (FAQ) in übersichtlicher Gliederung.
• Glossar mit Erklärung der Fachbegriffe.

Auf eine für die zu erwartenden Benutzer verständliche Sprache ist besonders zu achten.

Traditionell lieferte man schlicht ein Handbuch zur Software aus.

Das hat sich mit grafischen Benutzeroberflächen verändert. Sie sollten bereits selbsterklärend sein und intuitiv die richtige Bedienung nahelegen.

Zur Benutzerdokumentation gehören heute zusätzlich:

• Kontext-sensitive Hilfe an jeder Stelle des Programmablaufs.
• Online-Version eines gedruckten Benutzerhandbuchs auf der lokalen Festplatte, mit Hyperlinks und direktem Verweis auf einzelne Fundstellen aus der Hilfefunktion heraus.
• Aktualisierte Informationen auf der Website der Entwickler.
• Guided Tour durch die Benutzerführung als erster Einstieg.
• Agenten und Assistenten, die als regelbasiertes System durch gezielte Fragen an den Benutzer bei der Lösung komplexer Probleme helfen.

Siehe auch

• Technische Dokumentation
• Software-Dokumentationswerkzeug
• Capability Maturity Model
• Verfahrensdokumentation
• Fachkonzept

Einzelnachweise

1. ↑ Beckmann, in CR 9/98, S.519 ff.
2. ↑ juristisches Seminar für Handbuchautoren aus Anlass der Einführung des Produkthaftungsgesetzes