Dokumentation von Software

Software-Dokumentation der Software

Hebhard Greiter: Software Engineering, Informatik, Dokumentation: Mindestumfang, Entwurfsformular, Konzeptdokumentation, Testergebnis. mw-headline" id="Tips">Tipps Ein gutes Software-Dokument, sei es ein Lastenheft für Entwickler und Prüfer, ein Fachdokument für den internen Gebrauch oder Software-Handbücher und Hilfsdateien für den Endverbraucher, helfen der mit der Software arbeitenden Personen, ihre Merkmale und Funktionalitäten zu ergründen. Ein guter Software-Dokumentation ist konkret, genau und sachdienlich, sie gibt dem Menschen alle notwendigen Hinweise, um die Software zu nutzen.

Nachfolgend finden Sie eine Anleitung zum Verfassen von Software-Dokumentation für den technischen Benutzer und den Endanwender. Legen Sie fest, welche Daten aufgenommen werden müssen. Spezifikationen gelten als Referenzhandbuch für die Entwickler der Benutzungsoberfläche, die Entwickler, die den Quellcode verfassen, und die Tester, die sicherstellen, dass die Software wie beabsichtigt arbeitet. Der genaue Inhalt hängt vom jeweiligen Anwendungsprogramm ab, kann aber auch folgende Angaben enthalten:

Key Files innerhalb der Applikation. Entscheiden Sie, wie viel von der Dokumentation im Quelltext enthalten sein soll und wie viel davon abgetrennt werden soll. Mit zunehmender Einbeziehung der technischen Dokumentation in den Quellcode des Programms wird es umso leichter sein, diese mit dem Quellcode zu erneuern und zu warten sowie unterschiedliche Fassungen der Originalversion zu unterlegen.

Die Dokumentation im Quelltext sollte mindestens den Verwendungszweck der Befehle, Befehlsverzeichnisse, Variablen aufzeigen. Bei besonders langen Quelltexten kann die Dokumentation in Gestalt einer Hilfe-Datei bereitgestellt werden, die indiziert und dann nach Stichworten gesucht werden kann. Das ist besonders vorteilhaft für Applikationen, bei denen die Programlogik auf mehrere Sites verteilt ist und eine Vielzahl von Zusatzdateien beinhaltet, wie dies bei einigen Webanwendungen der fall ist.

Das NET Framework (Visual Basic, C#), hat einen eigenen Industriestandard für die Dokumentation innerhalb des Quellcodes. Bei diesen Arbeiten sollten Sie sich an die Vorgaben halten, wie viel Dokumentation im Quelltext enthalten sein sollte. Wählen Sie eine geeignete Applikation für die Dokumentation. Andernfalls wird die Applikation nach der Dokumentationsart festgelegt. Textverarbeitungsprogramme wie Microsoft Word reichen aus, um separate Testdateien der Dokumentation zu erstellen, sofern die Dokumentation kurz und unkompliziert ist.

Viele Fachautoren ziehen für lange, komplizierte Texte eine Dokumentationsapplikation wie Adobe FrameMaker vor. Mit jedem Autorentool für die Online-Hilfe, wie z.B. RoboHelp, Help and Manual, Doc-To-Help, MadCap Flare oder Helvelogix, können Hilfetexte zur Dokumentation des Quellcodes erstellt werden. Ermitteln Sie den betriebswirtschaftlichen Hintergrund für Ihre Dokumentation. Obwohl der eigentliche Zweck der Dokumentation von Software darin besteht, den Benutzern zu helfen, die Software zu begreifen, gibt es andere Faktoren, wie z.B. die Förderung der Softwarevermarktung, die Imageverbesserung des Unternehmens und vor allem die Senkung der Kosten für den technischen Support.

Im Einzelfall ist eine Dokumentation erforderlich, um bestimmte Vorschriften oder andere gesetzliche Bestimmungen einzuhalten. Allerdings sollte die Softwaredokumentation niemals ein Substitut für ein mangelhaftes Oberflächendesign sein. Benötigt ein Applikationsbildschirm eine Menge Dokumentation zur Erläuterung, dann ist es besser, das Aussehen der Bedienoberfläche auf etwas intuitiver zu umzustellen.

Verstehen Sie das Publikum, für das Sie den Dokumentarfilm schreiben. Meistens haben Nutzer weniger Kenntnisse über Rechner außerhalb der Tasks, die sie mit der Applikation ausführen. Sie haben mehrere Methoden, um den Bedarf in Ihrer Dokumentation zu ermitteln. Schauen Sie sich die Berufsbezeichnung des zukünftigen Benutzers an. Eine Systemadministration ist höchstwahrscheinlich ein Spezialist für eine Vielzahl von Softwareanwendungen, während ein Mitarbeiter der Datenerhebung nur die Applikation kennen dürfte, mit der er die erfassten Informationen gerade erfasst.

Werfen Sie einen Blick auf die Anwender selbst. Obwohl die Jobbeschreibungen in der Regel auf das Verhalten der Mitarbeiter hinweisen, gibt es signifikante Unterschiede in der Nutzung der Jobbezeichnungen in verschiedenen Betrieben. Werfen Sie einen Blick auf bestehende Dokumentarfilme. Die Dokumentation für Vorgängerversionen einer Software sowie die Spezifikationen können Ihnen einen Anhaltspunkt dafür liefern, was der Anwender wissen muss, um die Software nutzen zu können.

Geben Sie das entsprechende Ausgabeformat für die Dokumentation an. Die Software-Dokumentation kann in 2 verschiedene Formate gegliedert werden, als Referenz-Handbuch oder als Anwender-Handbuch. In einem Nachschlagewerk werden die Einsatzmöglichkeiten einer Software-Anwendung (Schaltflächen, Tabs, Eingabefelder und Dialogfelder) und deren Funktionalität behandelt. Zahlreiche Online-Hilfen sind in diesem Dateiformat verfasst, insbesondere die kontextabhängige Hilfedatei, die ein wichtiges Topic anzeigt, wenn ein Anwender auf die Hilfetaste in einem speziellen Bildschirm drückt.

Eine Bedienungsanleitung erklärt, wie Sie die Software zur Ausführung einer bestimmten Funktion verwenden. Benutzeranleitungen bestehen oft aus Tutorials mit einer Übersicht über die anfangs gestellte Übung und einer Anleitung mit numerierten Arbeitsschritten mit einer Übersicht über die anfangs gestellte Übung und einer Anleitung zur Ausführung in numerierten Arbeitsschritten. Entscheiden Sie, welche Form(en) die Dokumentation haben soll(en).

Software-Dokumentationen für Endanwender können eine oder mehrere von vielen verschiedenen Arten annehmen: Druckversionen von Handbüchern, PDF-Dokumenten, Hilfe-Dateien oder Online-Hilfen. Jedes Formular soll dem Anwender die Nutzung aller Programmfunktionen erläutern, sei es in Gestalt eines Lernprogramms oder eines Handbuchs; bei Hilfe-Dateien und Online-Hilfen können Filme, Texte und Graphiken aufgenommen werden.

Hilfe-Dateien und Online-Hilfe sollten indiziert und mit Stichworten durchsucht werden, damit Anwender die gesuchten Daten rasch wiederfinden. Obwohl Autorentools für die Online-Hilfe den Suchindex automatisiert erzeugen können, ist es oft besser, den Suchindex mit den von Benutzern gesuchten Suchbegriffen aufzurufen. Wählen Sie die entsprechende Dokumentationsapplikation aus.

Unterteilen Sie die Dokumentation logischerweise in Themenbereiche und Inhalte. Alle oben genannten Dokumentationsapplikationen können durch eine Applikation zur Erstellung von Bildschirmfotos wie Snagit erweitert werden, wenn die Dokumentation eine Serie von Bildschirmfotos benötigt. Auch hier sollten Bildschirmfotos enthalten sein, um zu erläutern, wie die Software arbeitet, und nicht, um den Anwender zu irritieren.

Sound ist besonders bei der Erstellung von Software-Dokumentationen für Endanwender von Bedeutung. Sprechen Sie mit Benutzern mit "Ihnen" statt in der dritten Gruppe mit "Benutzer".

Mehr zum Thema