Software-Dokumentation

Softwaredokumentation: Grundlagen und Aufbau

Softwaredokumentation ist eine Anleitung, wie Software genutzt werden soll und wie diese funktioniert. Sie ist ein essenzielles Element, um Transparenz und Funktionalität während des gesamten Software-Lebenszyklus zu gewährleisten.

Die Dokumentation besteht aus folgenden Teilen:

1. Methodendokumentation
   • Beschreibt die grundlegenden Methoden der Software, wie z. B. mathematische Algorithmen.
   • Wird aus Sicht der Anwender (z. B. Auftraggeber, Kunden) verfasst.
2. Programmiererdokumentation
   • Enthält technische Details wie die Beschreibung des Quellcodes, die erforderliche Hardware und Software (z. B. Betriebssysteme) sowie Anleitungen zur Installation, Pflege und Deinstallation.
   • Umfasst auch begleitende Dateien wie Readme.txt.
3. Datendokumentation
   • Beschreibt die Struktur und Bedeutung der Daten, die von der Software genutzt werden.
   • Unterteilt in:
     • Interne Datenstrukturen (nur für Entwickler sichtbar).
     • Externe Datenstrukturen (für Anwender sichtbar, z. B. Schnittstellen für Import und Export).
4. Textdokumentation
   • Dokumentiert Testfälle und beschreibt, welche Methoden zur Überprüfung der Software genutzt wurden.
5. Entwicklungsdokumentation
   • Nachweis von Software-Versionen (Patch- und Release-Notes).

Lasten- und Pflichtenhefte: Struktur und Bedeutung

Das Lastenheft und das Pflichtenheft sind zentrale Dokumente der Softwaredokumentation:

• Lastenheft
  • Definiert die Anforderungen des Auftraggebers.
  • Enthält allgemeine und flexible Formulierungen, um den Entwicklern Spielraum bei der Umsetzung zu geben.
  • Kann für Ausschreibungen genutzt werden, bei denen potenzielle Auftragnehmer Lösungen vorschlagen.
• Pflichtenheft
  • Wird vom Auftragnehmer erstellt und beschreibt, wie die Anforderungen aus dem Lastenheft erfüllt werden.

Gemäß DIN 69901-5 kann ein Lastenheft Tabellen, Grafiken oder Modellierungssprachen enthalten. Sein Aufbau umfasst:

• Einführung
• Beschreibung des Ist-Zustands und Soll-Konzepts
• Beschreibung von Schnittstellen
• Funktionale und nichtfunktionale Anforderungen (z. B. Benutzbarkeit, Zuverlässigkeit, Wartbarkeit)
• Risikoakzeptanz
• Systemarchitektur
• Lieferumfang

Technische Dokumentation: Interne und externe Aspekte

Die Technische Dokumentation ergänzt die Softwaredokumentation und deckt alle Phasen des Produktlebenszyklus ab. Gemäß VDI 4500 wird sie in zwei Kategorien unterteilt:

1. Interne Technische Dokumentation
   • Archiviert relevante Dokumente und Nachweise, darunter Pflichthefte, Versuchsberichte, Risikobeurteilungen, technische Zeichnungen und Fertigungsunterlagen.
   • Wird von der Entwicklungs- oder Konstruktionsabteilung geführt.
2. Externe Technische Dokumentation
   • Informiert Betreiber und Kunden über die sichere Nutzung, Inbetriebnahme und Entsorgung des Produkts.
   • Wird meist in mehrere Sprachen übersetzt (z. B. Gebrauchsanleitung, Installationsanleitung).
   • Gesetze und Vorschriften der EU (z. B. EG-Richtlinien) regeln die Bereitstellung.

Fehlerhafte oder unvollständige Dokumentationen können gemäß §823 BGB Haftungsansprüche auslösen.

Juristische und historische Perspektiven

Die juristische Sicht auf Software Dokumentation unterscheidet sich stark von der technischen. Für Juristen sind Aspekte wie Verbraucherschutz, Haftung und Gewährleistung zentral. Auch der Sprachgebrauch weicht von der technischen Industrie ab.

Historisch hat sich die Art der Dokumentation seit den 1960er-Jahren stark verändert:

• Zwischen 1980 und 2005 galten drei Normen der Informationsverarbeitung (DIN 66230, DIN 66231, DIN 66232), die jedoch abgeschafft wurden, da sie nicht mehr zeitgemäß waren.
• Früher wurden Programme auf Lochkarten gestanzt, und der Quellcode war schwer zu lesen. Kommentare und Flussdiagramme waren nötig, um Funktionen zu erklären.

Moderne Entwicklungen in der Softwaredokumentation

Heutzutage hat die Softwaredokumentation signifikante Fortschritte gemacht:

• Automatisierung: Mithilfe von Dokumentationswerkzeugen können Übersichten direkt aus dem Quellcode erstellt werden.
• Digitalisierung: Dokumentationen existieren fast ausschließlich digital. Änderungen werden meist stichpunktartig in Changelogs aufgeführt.
• Benutzerdokumentation:
  • Bietet kontextsensitive Hilfe, Online-Versionen von Handbüchern mit Hyperlinks und Guided Tours.
  • Professioneller Support verbessert die Customer Experience (CX) erheblich.

Fazit

Eine umfassende Softwaredokumentation ist unverzichtbar, um die Nutzung, Wartung und Weiterentwicklung von Software zu ermöglichen. Sie gewährleistet Transparenz für alle Beteiligten – vom Entwickler bis zum Endanwender.

Moderne Technologien und Standards haben die Effizienz und Zugänglichkeit der Dokumentation deutlich verbessert. Mit gut strukturierten Lasten- und Pflichtenheften, einer klaren technischen Dokumentation und der Berücksichtigung juristischer Anforderungen wird der Erfolg von Softwareprojekten nachhaltig gesichert.