Mit Softwaredokumentation bezeichnet man die Dokumentation von Software. Sie erklärt für Entwickler, Anwender (Auftraggeber, Kunde) und Endbenutzer 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
Die Dokumentation zu einem Softwareprodukt besteht aus unterschiedlichen Teilen, die auf verschiedene Zielgruppen (Nutzungskontext) ausgerichtet sind:
- 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. Die Methodendokumentation ist aus der Weltsicht der Anwender geschrieben.
- Programmiererdokumentation
- Beschreibung des Quellcodes.
- 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: Innere Datenstrukturen, wie sie nur für Programmierer sichtbar sind und Ä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 (z. B. in Patch- oder Releasenotes), 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:
- Projektdokumente
- Sie beschreiben, was von den Entwicklungsbeteiligten zu tun ist (bzw. war) – warum (z. B. Ziele, Anforderungen), wie (Methodik), wann (Planungsdokumente), womit (Werkzeuge) etc.
- Systemdokumente
- 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.
Juristische 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 Informationstechnik anpasst.
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
Wenngleich die dort standardisierte Papierform obsolet wurde, sind die Ziele und Grundprinzipien nach wie vor aktuell.
Programmiererdokumentation
Die ersten Anwendungsprogramme wurden auf Lochkarten gestanzt und hatten einen relativ geringen Umfang, also etwa einige Tausend Zeilen. Kommentare im Quellcode waren selten. Leerzeichen vermied man, wo syntaktisch zulässig, damit das ganze Statement in die 72–80 Spalten einer Karte passte und keine Folgekarte mitzuschleppen wäre. Nur Großbuchstaben waren möglich; die Länge der Namen von Variablen und Funktionen war stark begrenzt (oft nur 6 Zeichen). Der Quellcode war dadurch nur schwer lesbar. Die Programmiererdokumentation musste dann 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. Dafür erlauben moderne Programmiersprachen und unbegrenztes Textvolumen zusammen mit interaktiven Darstellungen ein anderes Vorgehen.
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 müssen; bei Änderungen des Programms kommt es sonst sofort zu Inkonsistenzen. Die personellen Ressourcen zur zeitnahen Pflege überflüssiger Dokumente sind regelmäßig nicht vorhanden.
- Die Dokumentation soll so weit 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 (Lebende Dokumentation) 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.
- In ein Änderungsprotokoll (englisch Changelog) werden stichwortartig Veränderungen dokumentiert, allerdings nicht ins Detail. Dabei wird vor allem auf Unterschiede zu vorangegangenen Versionen von Software Bezug genommen, wodurch ein Überblick geschaffen werden soll.
Benutzerdokumentation
Die Benutzerdokumentation dient dazu, den Benutzern die Anwendung des Programms zu erklären.
Zur Benutzerdokumentation gehören heute zusätzlich:
- Kontextsensitive 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.
Auf eine für die zu erwartenden Benutzer verständliche Sprache ist besonders zu achten.
Traditionell wurde schlicht ein Handbuch zur Software ausgeliefert. Das hat sich mit grafischen Benutzeroberflächen verändert. Sie sollten bereits selbsterklärend sein und intuitiv die richtige Bedienung nahelegen.
Ein gutes Benutzerhandbuch besteht aus:
- Informationen zur Funktionalität der Software, ihrer Eingabedaten und der erzeugten Ergebnisse – aus der Sicht des Anwenders/Benutzers.
- 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.
Siehe auch
Literatur
- Franz Lehner: Software-Dokumentation und Messung der Dokumentationsqualität. Hanser, 1994, ISBN 3-446-17657-8 (Endstadium der papiergestützten Formate; Grundlagen und inhaltliche Forderungen zeitlos).
Einzelnachweise
- ↑ Beckmann. In: CR, 9/98, S. 519 ff.
- ↑ juristisches Seminar für Handbuchautoren aus Anlass der Einführung des Produkthaftungsgesetzes
