Software Dokumentation

Software Dokumentation:

Software Dokumentation ist eine Anleitung, wie Software genutzt werden soll und wie diese funktioniert. Die Dokumentation besteht aus verschiedenen teilen.
Der erste Teil ist die Methodendokumentation, bei der die Grundlagen der Software (z.B. mathematische Algorithmen) dokumentiert werden. Diese ist aus der Sicht der Anwender (z.B. Auftraggeber, Kunde) geschrieben. Der zweite Teil ist die sogenannte Programmiererdokumentation welche folgendes beinhaltet: die Beschreibung des Quellcodes, die Installationsdokumentation, die zur Nutzung erforderliche Hardware und Software (Betriebssystem), eine Anleitung zur Installation und Pflege sowie zur Deinstallation und die Readme.txt Datei. Der dritte Teil der Softwaredokumentation ist die Datendokumentation, in der eine nähere Beschreibung der Daten und die Interpretation der Infos in der echten Welt (z.B. Formate, Datentypen, Beschränkungen) stehen. Außerdem ist diese in zwei Bereiche aufgeteilt: die inneren Datenstrukturen, welche nur für Programmierer sichtbar sind und die äußere Datendokumentation, welche für den Anwender sichtbar ist und Informationen von Endbenutzern sowie eine detaillierte Beschreibung möglicher Import-/Exportschnittstellen enthält. Der vierte Teil ist als Textdokumentation bekannt und enthält einen Nachweis von Testfällen, sowie eine Angabe darüber welche Methoden in der Vergangenheit genutzt wurden um die Richtigkeit der Software zu überprüfen. Der fünfte Teil der Softwaredokumentation ist als Entwicklungsdokumentation bekannt und enthält einen Nachweis der einzelnen Versionen (also Patch und Releasnotes). Für eine vollständige und richtige Softwaredokumentation werden außerdem noch Lastenhefte benötigt. Diese müssen alle an der Entwicklung beteiligten Personen und Organisationseinheiten, alle erfolgreichen und erfolglosen Entwicklungsrichtungen sowie alle Planungs- und Entscheidungsunterlagen beinhalten. Ebenfalls von Bedeutung sind die Projektdokumente, in denen steht womit, wie, wer, wann und warum etwas gemacht wurde. Zu beachten ist außerdem, dass auch die Systemdokumente teil der Softwaredokumentation sind. In diesen muss angegeben sein woraus das System besteht, was es tut, was es erzeugt, welche Daten es verarbeitet, wie es zu bedienen ist, etc. Wenn diese Unterscheidung bereits im Projektverlauf berücksichtigt wird, kann man den zum Erstellen der Systemdokumentation nötigen Aufwand minimieren. Die Juristische Sicht auf dieses Thema weicht stark von der der Informatik ab. Für Juristen ist bei Software der Aspekt des Verbraucherschutzes, der Haftung und Gewährleistung, etc. von Interesse. Aus diesen Grund, sowie weil Softwareprodukte für Juristen nur eine Variante von „Produkten“ unter diversen anderen ist, müssen auch bei Softwareprodukten eine Dokumentation erfolgen und vorliegen. Ebenfalls Interessant in dieser Hinsicht ist, dass der juristische Sprachgebrauch von dem der anwendenden Industrie abweicht. Softwaredokumentation war allerdings nicht schon immer auf diese weise und in diesem Umfang zu erledigen. Seit den 1960ern und 1970ern hat sich die Art und der Umfang stark gewandelt, so gab es zum Beispiel von 1980-2005 die drei Normen der Informationsverarbeitung DIN 66230 Programmdokumentation, DIN 66231 Programmentwicklungsdokumentation und DIN 66232 Datendokumentation. Diese wurden allerdings 2005 ohne Ersatz abgeschafft, weil sie nicht mehr zeitgemäß waren. Stark verändert hat sich auch die Programmierdokumentation bei der früher die Programme noch auf Lochkarten gestanzt wurden, Kommentare im Quellcode noch selten waren, der Quellcode als solcher schwer zu lesen war und die Programmierdokumentation noch separat mit einem Flussdiagramm Zeile für Zeile erklären musste, was die Funktionen des Programms sind. Heutzutage ist dies signifikant abgeändert, größtenteils weil sich die Technik immer weiter entwickelt. Während der Quellcode damals noch schwer zu lesen war, ist er heute selbsterklärend. Außerdem wird die Dokumentation in den Quellcode selbst eingebaut und aus ebenjenen Code kann man mittlerweile mithilfe von Dokumentationswerkzeugen automatisch unterstützende Übersichten erstellen lassen. Ebenfalls anders als früher ist, dass Übersichten, Notizen und andere Hilfsmittel, welche nicht im Quellcode integriert werden können, als Datei gemeinsam mit dem Quellcode gespeichert und verteilt werden müssen. Nennenswert in diesem Kontext ist auch, dass die Softwaredokumentation in der modernen Zeit nicht mehr auf Papier geschrieben wird sondern vollends digital existiert sowie, dass Änderungen (welche im Changelog angegeben sind) nicht mehr Detailliert verfasst sind sondern nur noch Stichpunktartig formuliert werden. Die Benutzerdokumentation dient dazu dem Kunden beziehungsweise dem Benutzer das Programm zu erklären. Deshalb enthält diese kontextsensitive Hilfe an jeder Stelle des Programms. Auch Notwendig um den Benutzer zu helfen ist, dass es Online Versionen des normalerweise gedruckten Benutzerhandbuches gibt, welches mithilfe von Hyperlinks auf die einzelnen Stellen der Hilfefunktion weiterleitet. Das alle aktuellen Infos auf der Website des Entwicklers zu finden sind, sowie das es eine Guided Tour als Einstieg gibt und das es die Möglichkeit gibt professionellen Support (Deutsch: „Hilfe“) zu erhalten, ist ebenfalls von maßgeblicher Bedeutung.

Neben der Softwaredokumentation gibt es auch die Technische Dokumentation, welche systematisch und strukturiert alle Informationsprodukte zur Nutzung, Wartung und Reparatur der Technik beinhaltet. Diese Dokumentation wird dem Produkt meist durch Namens- und Nummernsysteme eindeutig zugeordnet. Der Zweck der Technischen Dokumentation ist es zu informieren und zu instruieren. Die in dieser Dokumentation festgehaltenen Daten beinhalten: Informationen über das Produkt selbst, der Umgang mit den Nutzern, das Verhalten ebenjener, und sämtliche „Lebensphasen“ des Produkts von der Entwicklung bis hin zur Entsorgung. Man Unterscheidet hierbei nach VDI 4500 (Verein Deutscher Ingenieure) zwischen Interner und Externer Dokumentation. Die Interne Technische Dokumentation dient der Archivierung aller relevanten Dokumente und Nachweise und beinhaltet den gesamten Produktlebenszyklus von der Planung, über die Entwicklung, Markteinführung und Beobachtung bis hin zur Einstellung des Produkts. Diese Informationen bleiben beim Hersteller, welcher sie aktuell hält und archiviert. Bestandteile der internen Dokumentation sind: die Pflichthefte, die Berechnungsunterlagen, die Versuchsberichte, die Risikobeurteilungen, die Technischen Zeichnungen, die Fertigungsunterlagen, einen Nachweis über die Maßnahmen der Qualitätssicherung und die gesamte externe technische Dokumentation. Geführt wird diese interne Dokumentation von der Entwicklungs- oder Konstruktionsabteilung des jeweiligen Herstellers. Die Externe technische Dokumentation dient der Information der Betreiber/ Kunden und stellt sicher, dass das Produkt bestimmungsgemäß in Betrieb genommen, verwendet und entsorgt werden kann. Diese Dokumentation darf allerdings nicht vom Hersteller verfasst werden. Um zu garantieren, dass jeder diese verstehen kann, wird sie in der Regel in mehrere Sprachen übersetzt (z.B. Gebrauchsanleitung, Installationsanleitung, etc.). Die Bereitstellung der technischen Dokumentation ist durch Gesetze und Vorschriften vorgeschrieben. Diese Gesetze und Vorschriften sind in den Eu EG-Richtlinien, welche auch in nationales Recht umgesetzt wurden, festgelegt. Falls die technische Dokumentation fehlerhaft oder unvollständig ist, muss der Hersteller nach §823 Schadenersatzpflicht für einen Schadensfall Haften. Da die Dokumentation also von großer Bedeutung und leicht zu planen ist, sollte man sie gut Planen und gegebenenfalls während der Arbeit am Produkt erweitern. Die Struktur einer solchen Dokumentation muss logisch gegliedert und strukturiert sein. Um die Verständlichkeit zu verbessern muss sie außerdem in Gruppen thematisch oder analog zur Struktur zusammenfasst werden und mit Dokumentenlisten und Inhaltsverzeichnissen verwaltet werden. Während Fachkundige Leser keinerlei Probleme haben werden den Text zu verstehen, kann es für Thema fremde Leser schwer sein diese zu verstehen, da die Sprache, welche bei der technischen Dokumentation verwendet wird, viele komplizierte Fachwörter enthält, weshalb diese versuchen sollten sich über Thesauri anzunähern. Die Primärziele der Sprache sind Verständlichkeit, Eindeutigkeit, Konsistenz und Übersetzbarkeit. Diese Ziele können erfüllt werden, indem die Sprache durch Terminologie, Stil- und Grammatikregeln, Syntaxregeln und Interpunktionsregeln kontrolliert werden. Bei der Erstellung einer Technischen Dokumentation muss beachtet werden, dass alle technischen Funktionsbereiche einbezogen werden, dass Spezifikationen, Pflichthefte und Risikoanalysen sowie Unterlagen der Konstruktion und Fertigung erstellt werden und das Qualitätssicherungsunterlagen sowie Einkäufe nicht vergessen werden. Außerdem sollte beachtet werden, dass die externe Dokumentation meist von technischen Redakteuren verfasst wird.
Das Lasten-, Pflichtenheft (auch Anforderungsspezifikation, Anforderungskatalog, Produktskizze, Kundenspezifikation oder Anwenderspezifikation genannt) muss die Gesamtheit der Anforderungen des Auftragsgeber an den Auftragnehmers beinhalten. Die Formulierungen sollte hier so allgemein wie möglich und nur so einschränkend wie nötig sein, damit der Auftragnehmer in der Entwicklung möglichst frei ist. Das Lastenheft kann außerdem vom Auftraggeber für eine Ausschreibung genutzt werden. Mögliche Auftragnehmer schicken dann ein Pflichtenheft an den Auftraggeber, in dem beschrieben ist wie sie gedenken die Anforderungen aus dem Lastenheft zu erfüllen. Gemäß DIN 69901-5 beschreibt das Lastenheft die Gesamtheit der Forderungen des Auftragnehmers durch den Auftragsgeber und darf zur Präzisierung auch Tabellen, Zeichnungen, Grafiken oder Modellierungssprache enthalten. Der Aufbau eines Lastenheftes ist wie folgt: Einführung, Beschreibung des Ist-Zustands, Beschreibung des Soll-Konzepts, Beschreibung von Schnittstellen, Funktionale Anforderungen, Nichtfunktionale Anforderungen (Benutzbarkeit, Zuverlässigkeit, Effizienz, Änderbarkeit und Wartbarkeit), Risikoakzeptanz, Skizze des Entwicklungszyklus und der Systemarchitektur sowie der Lieferumfang.