Software-Dokumentation, Teil 3

Die Zielgruppe als Wegweiser

| Autor / Redakteur: Christian Rentrop / Stephan Augsten

In welcher Form die Dokumentation vorliegt, ist in vielen Fällen von der Zielgruppe abhängig.
In welcher Form die Dokumentation vorliegt, ist in vielen Fällen von der Zielgruppe abhängig. (Bild: Jessica Lewis - Unsplash.com)

In Software-Dokumentationen gilt es, neben bestimmten Norm-Vorgaben auch Dinge wie Ansprache und Zielgruppe zu beachten. Um die passende Dokumentation zu erstellen, sollten im Vorfeld einige Überlegungen angestellt werden.

Es gibt zahlreiche Gründe für die Erstellung einer Software-Dokumentation. Zudem kann eine Dokumentation in verschiedenen Formen vorliegen, etwa als Bestandsaufnahme, Quelltextkommentar, Endkunden-Anleitung oder technische Dokumentation für Ingenieure.

Gemeinsam haben alle Dokumentationsformen, dass sie Arbeitskraft binden, gegebenenfalls Fachabteilungen oder Externe beschäftigen und demzufolge Kosten verursachen: Die Art und der Umfang der Dokumentation sollte also im Vorfeld – noch bevor die erste Zeile Code geschrieben ist – zumindest theoretisch geklärt werden.

Welche Art der Doku soll es denn sein?

Vieles hängt dabei von der Zielgruppe ab, die den Code oder das fertige Programm später nutzen soll. Zudem ist es sinnvoll, zwischen internen Dokumentationsprozessen und externen wie etwa dem Benutzerhandbuch zu unterscheiden. Schließlich ergibt es beispielsweise keinen Sinn, auch nur ein Wort einer Anleitung zu schreiben, so lange das Programm funktional und optisch noch nicht fertig ist.

Gleichzeitig sollte eine Code-Dokumentation aber während der Programmierung im Code selbst erfolgen. Eine Projekt-Dokumentation hingegen wird bereits mit dem Start des Projekts begonnen und laufend gepflegt. Dementsprechend sinnvoll ist es, sich im Unternehmen oder auch als Einzelentwickler vorab Gedanken zu machen.

Bestimmte Dokumentations-Workflows – etwa die Quellcode-Dokumentation – können auch als fester Bestandteil interner Prozesse etabliert werden. Heißt: Jeder Programmierer hat den Quellcode auf eine bestimmte Weise zu kommentieren, jeder Projektleiter die Fortschritte des Projekts an sich. Wie genau das erfolgt, kann in größeren Unternehmen die Compliance festlegen.

Zielgruppe definieren

Alle Arten der Dokumentation stehen und fallen allerdings mit der Zielgruppe, die bei jeder Dokumentation an erster Stelle stehen sollte. Denn mit ihr verändern sich sowohl die Ansprache als auch Art und Umfang. Die Zielgruppe hängt nicht von der Dokumentations-Art, sondern von demjenigen ab, der die Dokumentation später lesen oder verwenden soll.

Beispiel Quelltext-Dokumentation: Ein Einzel-Entwickler, der keine Open-Source-Software erstellt, kann die Quelltext-Doku nach eigenem Gutdünken entwickeln, mit Abkürzungen arbeiten, sogar eine eigene Geheimsprache entwickeln oder die Doku komplett weglassen. Sobald jedoch ein Zweiter den Code lesen, verstehen oder sogar bearbeiten muss, ist es sinnvoll, sich auf einen Standard zu einigen: Hier setzt die Zielgruppen-Findung ein.

Skalierbarkeit im Blick behalten

Im Hinblick auf Skalierbarkeit des eigenen Projekts sollten also auch Einzel-Entwickler Quellcode-Dokumentation einsetzen und dabei immer den „unbekannten Entwickler“ im Hinterkopf haben. Schließlich könnte aus einem kleinen Einzelprojekt schnell ein Unternehmen erwachsen, in dem sich mehrere Coder mit dem Quelltext befassen müssen.

Dieser „Unbekannte“ ist im Grunde bekannt, ja er kann sogar per Klischee festgelegt werden: Er ist Techie, spricht fließend Englisch und versteht normalerweise Anspielungen auf die Geek-Popkultur. Selbst dann, wenn er eine Sie ist. Dementsprechend sinnfrei ist es, in der Quellcode-Doku eine eigene Geheimsprache zu entwickeln.

Wie dieser „unbekannte Entwickler“ genau aussieht, sollte aber jeder Programmierer selbst entscheiden – sofern er keiner Konzernrichtlinie unterliegt, die genau diese Geheimsprache fordert.

Die Zielgruppe der Endkunden-Dokumentation

Am anderen Ende des Dokumentationsprozesses steht der Endkunde: Dieser soll die Software kaufen und verwenden. Anders als zum Beispiel bei der technischen Dokumentation, wie sie etwa im Anlagenbau verwendet wird und die möglicherweise Normen unterliegt, ist die Endkunden-Dokumentation eines Casual- oder Business-Produkts – etwa einer Office-Suite oder eines Spiels – weitestgehend frei gestaltbar.

Doch auch hier spielt die Analyse der Zielgruppe eine große Rolle: Es gilt, einen „Normalnutzer“ zu definieren, der bestimmte Eigenschaften und Kenntnisse hat, der möglichst viel Schnittfläche mit der Zielgruppe hat. Wichtig dabei: Man sollte nicht den Anspruch haben, alle User mit einer solchen Dokumentation zu erreichen.

Der technisch versierte Anwender wird die Doku etwa nur nutzen, wenn er gar nicht weiterkommt. Ein unerfahrener Anwender hingegen liest möglicherweise das Handbuch von A bis Z durch, ehe er die Software auch nur installiert.

Ansprache durch Zielgruppe definiert

Mit der relevanten Zielgruppe ändert sich auch die Ansprache: Gamer schätzen eher eine fantasievolle und sogar literarisch anspruchsvolle Doku, während Office-User eher nach gezielten Lösungen suchen. Im Spielebereich benötigen komplexe Simulationen andere Handbücher als Casual-Games für das Smartphone, genau wie eine Bildbearbeitung à la Photoshop andere Kundenansprüche bedient als eine simple Filter-App.

Eher zweitrangig dabei ist, ob die Endkunden-Dokumentation deshalb als klassisches Handbuch oder PDF, Online-FAQ oder Helpdesk stattfindet; auch mehrere dieser Arten sind möglich. Und auch der Faktor Ansprache – unterhaltsam, technokratisch, zielorientiert – hängt stark davon ab, wer die Anleitung später nutzen soll.

Eine nicht ganz unwichtige Rolle spielt natürlich auch, wie der Software-Entwickler sich selbst und sein Produkt sieht. Die joviale Duzerei, die sich etwa bei Apple durch alle Endkunden-Dokumente zieht, käme bei typischen Microsoft-Office-Kunden wohl eher negativ an.

Technische Dokumentation muss Standards entsprechen

Während der Entwickler bei der Endkunden-Dokumentation, ähnlich wie bei der Quelltext- und Projektdokumentation, eher frei in der Gestaltung ist, ist das bei einer technischen Dokumentation nicht der Fall: Hier gibt es aus Haftungsgründen zahlreiche Standards zu beachten. Wer ein typisches Handbuch, selbst eines für Endkunden, in die Hand nimmt, wird zunächst von einer Reihe von Warnungen erschlagen – auch das ist eine Folge des Haftungsrechts.

Normen wie der „Klassiker“ DIN EN 82079-1 oder VDI 4500 sind hierbei zu beachten und einzuhalten, um eine einheitliche und sichere technische Dokumentation zu erstellen. Gerade bei komplexen Anlagen – und dazu zählen eben auch Software-Systeme – ist es wichtig, Haftungsansprüchen durch Erstellung einer korrekten Anleitung vorzubeugen.

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: 45704385 / Software-Erstellung)