Software-Dokumentation, Teil 1 Hilfestellung für Entwickler, Tester und Anwender

Die Software-Dokumentation gehört zu den als lästig empfundenen Pflichtübungen bei der Softwareentwicklung. Doch es gibt gute Gründe, die Dokumentation zu verfassen und zu pflegen.

Anbieter zum Thema

PresseBox - unn | UNITED NEWS NETWORK GmbH

FIS Informationssysteme und Consulting GmbH

Confluent Germany GmbH

Trotz vieler Fortschritte in der Benutzerführung und Bedienung ist moderne Software in aller Regel komplex: Zahllose Zeilen Code und verschiedene Bibliotheken werden verknüpft, um letztlich ein zeitgemäßes Software-Produkt zu entwickeln. Das Problem dabei: Sowohl für den Anwender, als auch für andere Programmierer ist ein Stück Software schlimmstenfalls zunächst ein Buch mit sieben Siegeln.

Beide müssen im Zweifel verstehen, wie die Software funktioniert. Möglich wird das mit Hilfe der Software-Dokumentation: Ist diese korrekt und verständlich verfasst, dient das nicht nur der Nutzerfreundlichkeit, sondern hilft auch dabei, Projekte intern oder bei Open-Source-Projekten von fremden Entwicklern weiterentwickeln zu können.

Gute Gründe für die Dokumentation

Die klassische Anwender-Dokumentation, die jeder von uns als „Gebrauchsanleitung“ kennt, ist dabei allerdings der letzte Schritt: Diese kann zum Beispiel von technischen Redakteuren, Technikjournalisten oder speziellen Agenturen verfasst, sprich ausgelagert werden, sobald das Software-Produkt fertig ist.

Deutlich wichtiger ist jedoch die interne Dokumentation des Codes für Entwickler. Diese stellt sicher, dass ein mit einem Software-Projekt betreuter Programmierer „ersetzt“ werden kann. Krankheit oder Unfall, Schwangerschaft oder Kündigung können jeden mit einem Projekt betreuten Entwickler/in jederzeit für Wochen, Monate oder für immer aus dem Verkehr ziehen.

In solchen Fällen muss sich sein oder ihr Vertreter schnell in das Projekt einarbeiten können. Vor allem bei teuren Freelancern, die als Ersatz ins Haus geholt werden, kann eine fehlende, fehlerhafte oder unvollständige Dokumentation schnell dazu führen, dass enorme Rechnungssummen auflaufen. Fehlt die Dokumentation, dauert es meist nicht lange, bis der Vorschlag kommt, das gesamte Projekt von Grund auf neu zu coden.

Dokumentationszeit sparen ist unklug

Von daher ist es sinnvoll, noch vor der ersten Zeile Code mit der Software-Dokumentation zu beginnen. Leider stehen dieser recht simplen Erkenntnis oft Zeit- und Kostendruck gegenüber. Unternehmensintern wird auf die Dokumentation verzichtet, weil diese letztlich effektive Programmierzeit kostet oder zusätzliche Mitarbeiter benötigt.

Doch das ist zu kurz gedacht. Aufgrund der oben genannten Probleme kann eine nicht ausreichende Dokumentation am langen Ende der Entwicklung enorme Kosten verursachen. Mit anderen Worten: Wer vorne sparen möchte, wird hintenheraus möglicherweise draufzahlen, von der damit verbundenen Verzögerung ganz zu schweigen.

Im Quellcode dokumentieren kann helfen

Dabei lässt sich eine brauchbare Software-Dokumentation für Entwickler ohne Weiteres auch „on the fly“ erstellen: Der Coder muss nur im Quellcode mittels Kommentar-Funktion kurz erklären, was er an dieser Stelle gemacht hat – und warum. Kurze Sätze helfen Drittentwicklern, die Schritte zu verstehen, die unternommen wurden, ohne dass diese Art der Dokumentation viel Aufwand erfordert.

Zusätzlich empfehlen sich jedoch noch weitere Dokumentationsschritte. So sollten zum Beispiel Programmierschnittstellen (APIs) der Software separat dokumentiert werden, um diese separat vom Quellcode nutzen oder anbieten zu können. Etwa, wenn ein Freelancer mittels API eine Zusatzfunktion integrieren soll.

Zu guter Letzt sollte es auch eine grundsätzliche Dokumentation der Software in Form eines Pflichtenhefts geben. Dadurch wird sichergestellt, dass sich auch größere Katastrophen – etwa der Ausfall eines Projektverantwortlichen – abfangen lassen.

Funktional oder handlungsorientiert?

Übrigens: Grundsätzlich wird dabei zwischen der sogenannten funktionsorientierten und handlungsorientierten Software-Dokumentation unterschieden. Erstere dient vor allem dem technischen Verständnis der Software, um funktional zu verstehen, was wo wie passieren muss.

Diese Art der Dokumentation richtet sich vor allem an Programmierer, bei deren Arbeit es weniger darauf ankommt, wie genau die Software geschrieben wird – solange die Funktion gegeben ist. Der handlungsorientierte Ansatz ist eher für Tester und Endkunden gedacht: Bestimmte Ziele oder typische Aufgaben der Software können hier zielführend beschrieben werden.

Dokumentation für den Endkunden

Die typische „Gebrauchsanleitung“ von Anwendersoftware, die wohl jeder kennt, der schon ein Betriebssystem oder Office-Programm verwendet hat, enthält daher meist beide Ansätze: So werden erst Funktionen beschrieben, anschließend typische Aufgaben in Form kleiner Workshops erklärt.

Welche Form der Aufbereitung letztlich sinnvoll ist, hängt jedoch vor allem davon ab, welche Zielgruppe bedient werden soll: Eine Dokumentation der Steuersoftware einer Werkzeugmaschine muss sicherlich anderen Anforderungen genügen als die einer kleinen Textverarbeitung für den Privatgebrauch.

Während erstere ein dickes Handbuch benötigt, wird letztere möglicherweise mit einer kleinen Online-FAQ ausreichend dokumentiert. Genau deshalb sollte diese Art der Dokumentation auch an Experten abgegeben werden; diese erarbeiten zusammen mit den Ingenieuren anhand der Unternehmens- und Zielgruppenvorgaben die passende technische Dokumentation für den Endkunden.

Nutzen in aller Regel höher als die Kosten

Trotzdem sollte, wie auf die interne Dokumentation, in keinem Fall Hilfestellung für den Anwender in Form einer technischen Dokumentation, Gebrauchsanleitung oder FAQ verzichtet werden. Auch wenn diese teuer und aufwändig erscheint, hat sie, neben gewährleistungsrechtlichen Aspekten, auch einen kostensparenden Effekt.

Eine gut verfasste und gepflegte Anleitung zu einem Produkt hat nämlich den Vorteil, dass der Anwender sich im Zweifel bei einem Problem selbst helfen kann. Je weniger technisch versierte Anwender hier die Hilfestellung bekommen, umso besser: Das wiederum entlastet die noch viel kostspieligere Support-Abteilung oder, bei kleineren Unternehmen oder Einzelentwicklern, die lästige Bindung von Arbeitszeit durch die Beantwortung von Fragen oder das Geben von Hilfestellung für User, die sich im Programm nicht zurechtfinden.

Dokumentation ist immer sinnvoll

Schon bei den beiden Aspekten Code- und Anwender-Dokumentation wird schnell deutlich, dass die scheinbar lästige und teure Dokumentation durchaus ihre Existenzberechtigung hat und sich die Erstellung in den allermeisten Fällen lohnt. Eine gut geplante Software-Dokumentation für Entwickler kann dafür sorgen, dass ein Projekt zeitig zum Abschluss kommt, selbst wenn wichtige Protagonisten ausfallen. Gleichzeitig kann eine gute Anwenderdokumentation die Personalkosten im Support enorm reduzieren.

(ID:45669974)