Software-Dokumentation, Teil 4

Die richtige Dokumentation für jeden Zweck

| Autor / Redakteur: Christian Rentrop / Stephan Augsten

Eine ordentliche In-Line-Dokumentation hilft nicht nur der eigenen Erinnerung sondern auch später hinzukommenden Entwicklern auf die Sprünge.
Eine ordentliche In-Line-Dokumentation hilft nicht nur der eigenen Erinnerung sondern auch später hinzukommenden Entwicklern auf die Sprünge. (Bild: Christina Morillo - Pexels.com)

Die Software-Dokumentation ist grundsätzlich sinnvoll und nicht selten unabdingbar. Doch welche Formen der Dokumentation sind überhaupt zwingend notwendig? Schließlich gibt es ja auch Software ohne jede Form der Dokumentation. Sinnvoll ist das aber nicht.

Wenn Software entwickelt wird, ist es ratsam, einige Planungsschritte einzubauen. Einfach drauflos hacken kann gerade bei komplexen Projekten schnell im Chaos ausarten. Sicher: Gerade freie App-Entwickler und kleinere Entwicklerteams sparen sich die Kostenfaktoren Software-Dokumentation und Benutzerhandbuch gerne.

Was kurzfristig Geld und Aufwand spart, kann aber langfristig zu einem Problem werden: Spätestens, wenn die Firma wächst und sich neue Entwickler und Projektleiter mit der Software beschäftigen müssen, explodiert ohne Dokumentation der Mehraufwand. Doch die Dokumentation hat noch einen anderen Aspekt: Was braucht oder wünscht der Kunde?

Keine gesetzliche Dokumentationspflicht

Zunächst einmal gibt es grundsätzlich keine Dokumentationspflicht für Software in Deutschland oder der EU. Auch weltweit sind entsprechende Regelungen eher untypisch, was damit zusammenhängt, dass an dieser Stelle kein gesetzlicher Regelungsbedarf besteht. Vielmehr betreffen Dokumentationstypen primär das Haftungsrecht und verschiedene Produktsicherheitsgesetze.

Ohne hier zu tief in die Juristerei einsteigen zu wollen, kann dadurch zunächst abgeleitet werden, dass jeder Software-Hersteller zumindest dem Kunden gegenüber irgendeine Art der Dokumentation liefern muss. Gleichzeitig wird der Kunde diese bei komplexerer Software oder gar technischen Anlagen ohnehin einfordern.

Dokumentationstypen vorab festlegen

Sinnvoll ist es daher, schon bei der Planung einer Software genau festzulegen, welche Arten der Dokumentation vorhanden sein sollten. Das kann in Absprache mit dem Kunden erfolgen – etwa um technische Dokumentationen oder Handbücher zu erstellen. Auch ohne „festen“ Kunden ist es jedoch sinnvoll, trotzdem interne Dokumentationsvarianten festzulegen.

Von diesen lassen sich andere Dokumentationsformen nämlich im Fall der Fälle ableiten. So kann eine technische Dokumentation auf den internen Dokumentationstypen wie der Schnittstellen. oder Methodendokumentation eines Software-Unternehmens basieren – und hier dann hinten heraus Kosten und Aufwand sparen. Aus einer technischen Dokumentation lässt sich wiederum ein Benutzerhandbuch ableiten.

Letztlich ist im Hinterkopf zu halten, dass eine Dokumentation nie sinnfrei ist: Je mehr Material eines Dokumentationstyps vorhanden ist, mit desto weniger Aufwand lassen sich andere Dokumentationen erstellen. Gleichzeitig ist eine umfangreiche Dokumentation auch im Fall juristischer Streitigkeiten eine effiziente Möglichkeit, Vorwürfe auszuräumen.

Dokumentationsformen schon im Pflichtenheft festlegen

Wie und ob dokumentiert wird, ist wie gesagt auch eine Frage des Kunden. Wenn ein Unternehmen zum Beispiel programmieren lässt, den Code aber später zur eigenständigen Weiterentwicklung übernimmt, ist es sinnvoll, gewisse Dokumentationsformen bereits im Pflichtenheft oder im Auftrags-Vertrag festzulegen. Auf diese Weise wird vertraglich geregelt, welche Dokumentationen vorhanden sein müssen und wie diese anzufertigen sind.

Das betrifft sowohl große Development- und Service-Anbieter als auch freie Einzelentwickler, die von Dritten beauftragt werden: Ist die Dokumentationsform geregelt, spart das auf der einen Seite Mühe und auf der anderen Not. Wie genau die Dokumentation im Einzelnen auszusehen hat, lässt sich natürlich ebenfalls mit dem Auftraggeber oder Kunden regeln.

Im Zweifel lieber mehr dokumentieren

Doch auch, wenn die Fragen der Dokumentation nicht sauber geklärt werden, ist es sinnvoll, möglichst gut intern zu dokumentieren. Denn wer bei der Dokumentation schludert, kommt möglicherweise auch selbst irgendwann in die Bredouille – dann nämlich, wenn ein in die Jahre gekommenes Projekt später aktualisiert oder neu aufgelegt werden soll.

Es ist nicht unwahrscheinlich, dass ein Entwickler mit einigen Monaten oder Jahren Abstand selbst nicht mehr in der Lage ist, seinen Quellcode zu entziffern oder vergessene oder auf „später“ verschobene Entwicklungsschritte nachzuvollziehen. Eine hinreichend verständliche interne Dokumentation kann also auch dabei helfen, eigene Projekte wieder in Angriff zu nehmen. Dummerweise wird die Dokumentation gerade bei agilen Programmier-Prozessen gerne vergessen, was am Ende für Verwirrung sorgen kann.

Dokumentation auf das Notwendige beschränken

Übrigens: Grundsätzlich gilt in jeder Software-Dokumentation die Regel, die Informationen auf das wirklich Notwendige zu beschränken. So ist es im Quellcode nicht sinnvoll, riesige Kommentare zu schreiben, weil diese den Code unnötig aufblähen. Andere Dokumentationsformen können, sofern sie zu blumig formuliert sind, schnell dafür sorgen, dass noch mehr Verwirrung aufkommt.

In allen Formen der Software-Dokumentation ist dementsprechend Zurückhaltung gefragt. Denn letztlich gilt bei der Software-Dokumentation das gleiche wie bei der Code-Erstellung: Weniger ist mehr. Allerdings sollte dabei im Hinterkopf behalten werden, dass zum Beispiel eine technische Dokumentation gewissen Regeln und Normen unterliegt, die eingehalten werden sollten.

Kommentare werden geladen....

Kommentar zu diesem Artikel

Der Kommentar wird durch einen Redakteur geprüft und in Kürze freigeschaltet.

Anonym mitdiskutieren oder einloggen Anmelden

Avatar
Zur Wahrung unserer Interessen speichern wir zusätzlich zu den o.g. Informationen die IP-Adresse. Dies dient ausschließlich dem Zweck, dass Sie als Urheber des Kommentars identifiziert werden können. Rechtliche Grundlage ist die Wahrung berechtigter Interessen gem. Art 6 Abs 1 lit. f) DSGVO.
  1. Avatar
    Avatar
    Bearbeitet von am
    Bearbeitet von am
    1. Avatar
      Avatar
      Bearbeitet von am
      Bearbeitet von am

Kommentare werden geladen....

Kommentar melden

Melden Sie diesen Kommentar, wenn dieser nicht den Richtlinien entspricht.

Kommentar Freigeben

Der untenstehende Text wird an den Kommentator gesendet, falls dieser eine Email-hinterlegt hat.

Freigabe entfernen

Der untenstehende Text wird an den Kommentator gesendet, falls dieser eine Email-hinterlegt hat.

copyright

Dieser Beitrag ist urheberrechtlich geschützt. Sie wollen ihn für Ihre Zwecke verwenden? Infos finden Sie unter www.mycontentfactory.de (ID: 45719404 / Software-Erstellung)