imported>Invisigoth67: typo

2024-11-03T15:53:08Z

typo

Neue Seite

Mit '''Softwaredokumentation''' bezeichnet man die [[Dokumentation]] von [[Software]]. Sie erklärt für [[Softwareentwickler|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  {{Anker|Methodendokumentation}}
: Allgemeine Beschreibung der Grundlagen, auf denen die Software beruht. Dies können mathematische [[Algorithmus|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|Programmiererdokumentation]]
: Beschreibung des [[Quelltext|Quellcodes]].
; Installationsdokumentation
: Beschreibung der erforderlichen [[Hardware]] und Software, mögliche [[Betriebssystem]]e und -Versionen, vorausgesetzte Software-Umgebung wie etwa [[Standardbibliothek]]en und [[Laufzeitumgebung|Laufzeitsysteme]]. Erläuterung der Prozeduren zur Installation, außerdem zur Pflege (Updates) und De-Installation, bei kleinen Produkten eine [[Readme]]-Datei.<br /> Zielgruppe sind [[Administrator (Rolle)|Administratoren]] beim Anwender, die die Software nicht zwangsläufig unmittelbar selbst nutzen müssen.
; [[#Benutzerdokumentation|Benutzerdokumentation]]
: Informationsmaterial für die tatsächlichen [[Endbenutzer]], etwa über die [[Benutzerschnittstelle]]. Den Anwendern kann auch die [[#Methodendokumentation|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, [[Datentyp]]en, Beschränkungen (Wertebereich, Größe) zu benennen. Die Datendokumentation kann oft in zwei Bereiche aufgeteilt werden: Innere [[Datenstruktur]]en, 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 [[Konvertierung (Informatik)|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 [[Softwareanforderung|Anforderungen]] und der als Vorgaben benutzten Konzepte (z. B. in [[Lastenheft]]en und [[Pflichtenheft]]en); 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 (Recht)|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:<ref>Beckmann. In: ''CR'', 9/98, S. 519 ff.</ref> „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 [[Gebrauchsanleitung]]en 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:<ref>juristisches Seminar für Handbuchautoren aus Anlass der Einführung des [[Produkthaftungsgesetz]]es</ref> 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.

== 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-Norm|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 [[Lochkarte]]n 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 [[Programmablaufplan|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 [[Namenskonvention (Datenverarbeitung)|selbsterklärend]] sein.<br /> 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 [[Kontrollstruktur]]en 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.<br /> Das kann durch [[Kommentar (Programmierung)|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 [[Software-Dokumentationswerkzeug|Dokumentationswerkzeugen]] automatisch aus dem Quellcode und speziell formatierten Kommentaren generiert werden.<br /> [[Dienstprogramm]]e wie etwa [[Javadoc]] oder [[Doxygen]] können komplexe [[Hypertext]]e als Referenz erstellen, mit denen sich die Entwickler schnell auch in umfangreichen Systemen zurechtfinden können. [[Integrierte Entwicklungsumgebung]]en stellen interaktiv auch grafische Übersichten wie etwa Strukturbäume zusammen. Die Datenstruktur von [[Objekt (Programmierung)|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 [[Hyperlink]]s, Suchfunktionen und dynamisch durch Ein- und Ausblenden wechselnde Ansichten auf die Informationsmenge.
* In ein [[Änderungsprotokoll]] ({{enS|Changelog}}) werden stichwortartig Veränderungen dokumentiert, allerdings nicht ins Detail. Dabei wird vor allem auf Unterschiede zu vorangegangenen [[Version (Software)|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 [[Hilfedatei|Hilfefunktion]] heraus.
* Aktualisierte Informationen auf der Website der Entwickler.
* [[Guided Tour (E-Learning)|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 [[Grafische Benutzeroberfläche|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 [[Eingabe und Ausgabe|Eingabedaten]] und der erzeugten Ergebnisse – aus der Sicht des [[Benutzer|Anwenders/Benutzers]].
* Eine grundlegende [[Gebrauchsanleitung|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 [[Terminus|Fachbegriffe]].

== Siehe auch ==
* [[Technische Dokumentation]]
* [[Software-Dokumentationswerkzeug]]
* [[Capability Maturity Model]]
* [[Verfahrensdokumentation]]
* [[Fachkonzept]]

== 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 ==
<references />

[[Kategorie:Softwaretechnik]]
[[Kategorie:Technische Dokumentation]]

Softwaredokumentation - Versionsgeschichte

imported>Invisigoth67: typo