Software-Dokumentation, Teil 2 Dokumentationsarten in der Übersicht

Software-Dokumentation ist nicht gleich Software-Dokumentation: Es gibt verschiedene Spielarten und Varianten, die sich je nach Projekt und Zielgruppe unterschiedlich gestalten können. Wir erklären die gängigsten Arten.

Anbieter zum Thema

Insider Research

OutSystems

Im ersten Teil dieser Reihe haben wir die Notwendigkeit der Software-Dokumentation erklärt. Dass es sinnvoll ist, sowohl intern als auch extern eine Dokumentation anzulegen, um Abläufe in der eigenen Entwicklungsabteilung und beim Kunden zu optimieren.

Auf lange Sicht lässt sich dadurch Geld für Support oder die Neuprogrammierung von Projekten sparen, wie auf der Hand liegen dürfte. Allerdings gibt es verschiedene Arten der Software-Dokumentation, die sich je nach Projekt, internen Abläufen, Kundenstamm und Zielgruppe mehr oder weniger anbieten. Die Wichtigsten wollen wir Ihnen im Folgenden vorstellen.

Programmierdokumentation (Inline Source Documentation)

Die grundlegendste Form der Dokumentation, die jeder Entwickler durchführen kann, ist die Programmierdokumentation. Während der Entwicklung werden Kommentare im Quellcode eingefügt, die die einzelnen Schritte kurz erklären. Dadurch können andere Entwickler schnell und ohne aufwändige Code-Analyse nachvollziehen, warum dieser oder jener Code-Schnipsel im Quelltext steht und welche Funktion er hat.

Diese Methode bietet sich vor allem dann an, wenn Open-Source-Projekte erstellt werden sollen. Aber auch Einzelentwickler und kleine Unternehmen können mit dieser Art der Dokumentation die Doku sozusagen direkt beim Coden erstellen, wodurch der Aufwand minimiert wird. Allerdings verlangt diese Methode Entwicklern ab, dass sie die codeinterne Dokumentation auch ausreichend pflegen. Zudem bietet diese Form der Dokumentation keine Übersicht der Funktionen und eignet sich deshalb alleinstehend nicht für umfangreiche Projekte, sondern dient eher als Ergänzung.

Methodendokumentation

Die Methodendokumentation empfiehlt sich vor allem für größere Projekte oder Unternehmen, in denen die konkrete Umsetzung in Code zweitrangig ist. Die Methodendokumentation enthält Inhalte auf der „Meta-Ebene“, sprich: Algorithmen, Flussdiagramme, technische, wissenschaftliche oder kaufmännische Hintergründe der Software.

Die Methodendokumentation geht dabei weniger auf die Details der Programmierung ein, sondern legt, wie der Name sagt, die Methoden fest. Im Grunde handelt es sich um eine Art detailliertes Pflichtenheft, mit dessen Hilfe sich ein Mitarbeiter zum Beispiel bei einem Projektleiter-Wechsel schnell in die Thematik einlesen kann. Allerdings ist sie weniger technisch gehalten, um Hürden niedrig zu halten.

Schnittstellendokumentation

Mit Hilfe der Schnittstellendokumentation können die vorhandenen und genutzten Schnittstellen wie Bussysteme, Laufzeitumgebungen, GUIs, Webdienste oder APIs schnell und einfach zusammengefasst werden. Auf diese Weise können sich Entwickler und Projektleiter schnell eine Übersicht der externen Möglichkeiten der Software sowie der verwendeten Technologien verschaffen.

Gleichzeitig erhält das Team durch diese Art der Dokumentation eine Handreichung der Möglichkeiten der Software. Dadurch können Redundanzen und damit unnötiger Aufwand – Stichwort menschliche und technische Ressourcen – vermieden werden. Gibt es Plugin-Schnittstellen oder APIs für Dritte, können diese hier ebenfalls beschrieben und gegebenenfalls bei Bedarf an andere Entwickler herausgegeben werden.

Technische Dokumentation

Anders als andere Dokumentationsformen ist die technische Dokumentation eine Pflichtübung, denn sie ermöglicht es, die gesamten technischen Hintergründe und Funktionen sowie Bedienhinweise in einem Dokument zu vereinen. Sie bietet sich überall dort an, wo Anwender Hintergrundinformationen zu den verwendeten Technologien erhalten sollen – also im Grunde immer.

Die technische Dokumentation kann auch eine Installationsdokumentation oder bei Geräten natürlich Wartungsanweisungen und Explosionszeichnungen andere Dokumentationen – etwa die Schnittstellendokumentation – enthalten; gleichzeitig besitzt sie auch Überschneidungen mit der Benutzerdokumentation oder der Methodendokumentation.

Letztlich kann man die technische Dokumentation als technisch sehr ausführliches Handbuch beschreiben, das sich nicht an Endanwender, sondern an andere Techniker, Ingenieure, Administratoren oder Programmierer richtet. Die Zielgruppe kann dabei intern oder extern sein, jedoch ist sie immer professionell. Daher bietet sich eine technische Dokumentation vor allem dort an, wo Software von Technikern bedient werden muss, etwa im Anlagenbau, in der Robotik oder bei der Softwareentwicklung für die Industrie.

Für ihre Erstellung können verschiedene ISO-Normen herangezogen werden, zudem sollte die Dokumentation so verfasst sein, dass sie juristischen Problemen – Stichwort Produkthaftung – vorbeugt. Wie bei der -> Benutzerdokumentation kann es sich daher empfehlen, die Erstellung an spezialisierte Agenturen oder eigene interne Abteilungen abzugeben.

Benutzerdokumentation („Handbuch“)

Die Benutzerdokumentation ist das Benutzerhandbuch. Es gibt deutliche Überschneidungen zur technischen Dokumentation, die so weit gehen, dass die Begriffe synonym verwendet werden. In vielen Fällen werden Benutzerdokumentation und technische Dokumentation allerdings auch in einem Dokument zusammengefasst oder besitzen deutliche Überschneidungen.

Inhalt und Umfang sind dabei stark vorn der Zielgruppe abhängig, richten sich aber immer an den Benutzer. Dieser soll mit Hilfe des Benutzerhandbuchs lernen, die Software zu benutzen. Wie das konkret aussieht – etwa über Beschreibung der Funktionen oder in Form von How-Tos – ist natürlich dem Verfasser überlassen.

Wichtig ist, dass die Benutzerdokumentation im Zweifel technisch weniger versierte Zeitgenossen ansprechen soll, etwa Mitarbeiter im Vertrieb. Dementsprechend sollten technische Details und Funktionsbeschreibungen zugunsten konkreter Anwendungsbeispiele in den Hintergrund treten.

Das A und O an der Benutzerdokumentation ist, dass sie so verfasst ist, dass keine Haftungsprobleme auftreten. Missverständnisse und Fehler sollten dementsprechend tunlichst vermieden werden. Es empfiehlt sich bei umfangreichen Softwareprojekten daher, eine spezialisierte Agentur oder eine interne Dokumentationsabteilung mit der Erstellung zu beauftragen, die juristische Fallstricke ausmerzt. Bei kleinen Software-Projekten – etwa Smartphone-Apps – kann aber auch eine einfache FAQ ausreichen.

Software-Dokumentation, Teil 1

Hilfestellung für Entwickler, Tester und Anwender

(ID:45675032)