Dokumentation Software

Doku-Software für die Dokumentation

Dokumentation ist eine geordnete Zusammenstellung und Nutzung von Informationen zur weiteren Verwendung. Die Dokumentation ist das Stiefkind der Softwareentwicklung. Der Aufbau der einzureichenden Software-Dokumentation sollte nach dem folgenden Schema erfolgen.

mw-headline" id="Arten">Arten[Bearbeiten | < Quelltext bearbeiten]

Software-Dokumentation ist die Dokumentation von Software. Es erläutert Entwicklern, Benutzern und Anwendern in verschiedenen Funktionen, wie die Software arbeitet, was sie generiert und bearbeitet (z.B. Daten), wie man sie verwendet, was für ihren Einsatz benötigt wird und auf welcher Grundlage sie erstellt wurde. In der Gesamtdokumentation zu einem Produkt sind unterschiedliche Teile enthalten, die auf unterschiedliche Nutzergruppen zielen: z.B:

Verfahrensdokumentation Generelle Darstellung der Grundsätze, auf denen die Software basiert. Dabei kann es sich um Rechenalgorithmen, technisch-wissenschaftliche oder kommerzielle Prozeduren handeln, auf die in den anderen Dokumentationsbestandteilen hingewiesen werden kann. Das Programm setzt diese Mittel ein, aber die Verfahrensdokumentation bezieht sich nicht auf die technischen Einzelheiten der Programmgestaltung, die sich öfter verändern können. Der Methodennachweis stammt aus der Praxis der Benutzer.

Dokumentation des Programmierers Erläuterung des Quellencodes. Installationsunterlagen Bezeichnung der benötigten Hard- und Software, möglicher Betriebsysteme und Versionen, der benötigten Softwareumgebung wie z. B. Standard-Bibliotheken und Auslaufsysteme. Zielgruppen sind Verwalter beim Nutzer, die die Software nicht unbedingt selbst direkt benutzen müssen. Die Verfahrensdokumentation kann auch den Benutzern zur Verfügung gestellt werden, um Hintergründe und ein generelles VerstÃ?ndnis der Softwarefunktionen zu erlernen.

Interne Informationsstrukturen, die nur für den Programmer zugänglich sind, und externe Datendokumentationen für benutzerdefinierte Informationselemente - vom Endbenutzer zu erfassende und von der Software auszugebende Information. Dies beinhaltet auch eine ausführliche Darstellung der möglichen Import-/Export-Schnittstellen. Ein Teil der Dokumentation bleibt für die Entwicklung geheim, ein anderer Teil muss für die Benutzer zugänglich sein.

Zusammengefasst lässt sich die Software-Dokumentation nach folgenden Kriterien unterscheiden: Projektdokumentation Sie erläutern, was von den Entwicklungsteilnehmern zu tun ist (oder war) - warum (z.B. Zielsetzungen, Anforderungen), wie (Methodik), wann (Planungsdokumente), mit was (Werkzeuge) usw. - Projektdokumentation ist ein Dokument, das den Entwicklungsprozess beschreibt. Systemunterlagen Sie erläutern das Gesamtsystem - was es ausmacht, was es leistet (Funktionen), was es generiert (Ergebnisse), welche Informationen es bearbeitet, wie es zu verwenden ist, etc.

Das Recht sieht Software aus einem ganz anderen Gesichtspunkt als die Computerwissenschaft, z.B. in Bezug auf Konsumentenschutz, Haftpflicht und Gewähr..... Software-Produkte sind neben vielen anderen Typen nur eine Variation von "Produkten". Unter diesem Gesichtspunkt beinhalten Software-Produkte auch Dokumentationen. Beckmann zitiert:[1] "Nach der ständigen Gesetzgebung des Bundesgerichtshofs zum Themenbereich "IT-Benutzerdokumentation" ist klar zu verstehen, dass die Softwarelizenzierung ungeachtet der jeweiligen Vertragsart nicht nur die Lizenzierung des Programmes, sondern auch die Lizenzierung der entsprechenden Progamminformationen erfordert.

Zu den " Anweisungen " gehören hier unter anderem Unterlagen wie die Gebrauchsanweisung. "Die " Dokumentation " im engeren rechtlichen Sinne hingegen beinhaltet nur Aufzeichnungen und Nachweise über die Produktentwicklung, d.h. über die Entwickung, Herstellung, Prüfung, Lieferung (sweg); Quelle:[2] Wenn sich der vorstehende Abschnitt auf die " IT-Benutzerdokumentation " bezieht, ist es natürlich eine gerichtliche Entscheidung, die sich an den Wortlaut der Informationstechnologie im Einzelfall anpaßt.

Seit den 1960er und 1970er Jahren bis heute hat sich der Charakter und Anwendungsbereich der Software-Dokumentation dramatisch verändert. Anmerkungen im Quelltext waren rar. Es waren nur Grossbuchstaben möglich; die Längen der Variablennamen und Funktionsnamen waren sehr limitiert (oft nur 6 Zeichen). Daher war der Quelltext schwierig zu lesen.

Die Bandbreite der aktuellen Software-Systeme und die Geschwindigkeit, mit der eine große Anzahl von Programmieren Veränderungen vornehmen kann, erlauben nicht mehr den traditionellen Ansatz. Die heutige Software-Dokumentation folgt unterschiedlichen Ansätzen: Die Quelltexte sollten sich selbst erklären. Der Name von Variablennamen und Funktionsnamen sollte für den Menschen leicht ersichtlich sein. Ist die formelle Programmsprache selbst bereits genügend erläutert und wird die Gliederung durch die entsprechende Einrückung und Ausdarstellung von Steuerungsstrukturen genügend klar, darf keine weitere und eigenständige Darstellung erfolgen - bei Programmänderungen treten Lücken und Unstimmigkeiten unmittelbar auf.

Für die zeitnahe Bearbeitung von überflüssigen Dokumenten sind die Personalressourcen in der Regel nicht verfügbar. Diese Dokumentation sollte so weit wie möglich in den Quelltext eingebunden werden. Dies kann durch Kommentaren und Kommentarzeile geschehen, die sich in der Regel nahe an den Vorgaben im Quelltext befinden und bei Änderungen umgehend geändert werden können. Wenn andere Programmer, die in der Lage sind, die Daten weiter zu verarbeiten, sind die aktuellen Anmerkungen immer verfügbar und können weiter bearbeitet werden.

Unterstützungsübersichten sollten mit Hilfe von Dokumentationstools aus dem Quelltext und besonders strukturierten Texten automatisiert erzeugt werden. Hilfsprogramme wie Javadoc oder Soxygen können komplizierte Referenzhypertexte erzeugen, die es den Entwicklern ermöglichen, große Systeme rasch zu durchsuchen. Können Annotationen, Zeichnungen und dergleichen nicht in den Quelltext selbst eingebunden werden, sollten sie als Datei direkt mit den zugehörigen Akten des Quelltextes abgelegt und zusammen vertrieben werden, so dass sie allen Programmierern zur Verfuegung steht und keine Unstimmigkeiten entstehen.

Zusätzlich zu dieser "inneren" Dokumentation gibt es oft auch eine "äußere" Dokumentation, die sich an andere Programmer richtet, die eine Programmieroberfläche verwenden. So können beispielsweise die elektronischen Unterlagen in ihrer jetzigen Gestalt in der ganzen Welt unmittelbar zur Verfügung gestellt werden. Mit Hilfe der Anwenderdokumentation wird dem Anwender die Verwendung des Programmes erläutert. Aktuelle Information auf der Webseite der Hersteller.

Agents und Wizards, die als regelbasierte Systeme dazu beitragen, komplexe Problemstellungen zu lösen, indem sie dem Anwender spezifische Fragestellungen stellen. Besonderes Augenmerk muss auf eine für die erwarteten Nutzer leicht zu verstehende Formulierung gelegt werden. Bisher wurde ein Benutzerhandbuch für die Software einfach mitgeliefert. Information über die Funktionsweise der Software, ihre Eingangsdaten und die generierten Resultate - aus Anwendersicht.

Dr. Franz Lehner: Software-Dokumentation und Qualitätsmessung der Dokumentation. Hanser, 1994, ISBN 3-446-17657-8 (Endphase papierbasierter Formatierungen; Grundlegende und inhaltliche Anforderungen zeitlos).

Mehr zum Thema