Softwaredokumentation umfasst teilweise sehr unterschiedliche Bereiche. Dies führt oft zu Missverständnissen. Sie lässt sich unterteilen nach der Nutzung (intern/extern), nach dem Informationstyp (Grundlagenwissen/Handlungsanleitungen/Referenzinformationen) sowie nach dem Medium (print/online/embedded).
Grob unterteilen lässt sich Softwaredokumentation allgemein in Dokumentationstypen für den internen Gebrauch beim Hersteller und in Dokumentationstypen zur Weitergabe an Kunden.
Typischerweise sind in einer Benutzerdokumentation mindestens drei grundlegend verschiedene Informationstypen enthalten:
Nur selten ist eine Vermischung dieser Informationstypen sinnvoll, denn sie werden zu ganz unterschiedlichen Zeitpunkten aber fast nie gleichzeitig benötigt. Oft werden diese Informationstypen daher sogar in unterschiedliche Dokumente oder Dokumentationsteile aufgeteilt, z. B. in ein „Benutzerhandbuch“ und in ein „Referenzhandbuch“.
Neben der inhaltlichen Ebene gibt es auch vom Medium her grundlegend unterschiedliche Typen von Softwaredokumentation:
Eine Softwaredokumentation für Benutzer sollte im Idealfall immer in einem globalen Kontext stehen: dem Kontext einer ganzheitlichen Software-User-Assistance. Dies sind alle Maßnahmen, die die Benutzer bei ihrer Nutzung der Software unterstützen. Neben der klassischen Dokumentation, bestehend aus Handbüchern und Online-Hilfen, gehören zu einer ganzheitlichen User-Assistance insbesondere auch
Anders als bei Technischer Dokumentation im Bereich Maschinen- und Anlagenbau gibt es bei Softwaredokumentation vergleichsweise wenige normative und regulatorische Vorgaben. Je nachdem, um welche Art von Softwaredokumentation es sich handelt, muss diese ihre Leser bestmöglich und zielgenau unterstützen. Alle wichtigen Informationen müssen vorhanden und leicht auffindbar sein, andererseits sollte sich die Softwaredokumentation auf die für ihre Zielgruppe wesentlichen Inhalte beschränken.
Die wichtigste und zugleich die am häufigsten vernachlässigte Anforderung an Softwaredokumentation ist: Eine Softwaredokumentation muss die Fragen der Kunden beantworten und sie befähigen, das Produkt vollständig und effizient zu nutzen. Mehr nicht! Es geht nicht darum, was wir in der Softwaredokumentation sagen möchten, sondern ausschließlich darum, was der Leser wissen will. Technische Details, auf die wir zurecht stolz sind, die die Leser aber nicht kennen müssen, haben in einer Softwareokumentation ebenso wenig verloren wie hochtrabende Phrasen und „Buzzwords“ aus der Marketing-Abteilung.
Die Kunst beim Erstellen von Softwaredokumentation besteht darin, mit der Softwaredokumentation genau die Wissenslücke zu schließen zwischen dem, was der Leser schon weiß, und dem, was er noch nicht weiß aber wissen muss. Weniger Information ist zu wenig, mehr Information ist zu viel.
Machen wir uns nichts vor: Niemand liest eine Dokumentation zum Spaß. Technische Dokumentation, und damit auch Softwaredokumentation, wird meist nur als lästiges Übel empfunden. Sie wird nur dann gelesen, wenn der Schmerz, eine Funktion nicht nutzen zu können, größer ist als der Schmerz, die Dokumentation lesen zu müssen. Es geht beim Erstellen von Softwaredokumentation also immer darum, den Schmerz beim Lesen möglichst gering zu halten.
Der Schmerz ist dann gering, wenn:
Anders als bei anderen Formen Technischer Dokumentation gibt es bei Softwaredokumentation kaum gesetzliche und aus bestimmten Normen resultierende Anforderungen. In den meisten Fällen gilt lediglich die generelle Grundanforderung an Dokumentation, dass sie die Kunden dazu befähigen muss, das Produkt vollständig und erfolgreich zu nutzen.
Zusätzlich können sich spezielle Erfordernisse basierend auf vertraglichen Vereinbarungen mit Kunden ergeben, oder aus besonders zugesicherten Eigenschaften. Wird zum Beispiel damit geworben, dass eine Software über eine spezielle Schnittstelle verfügt, dann muss diese Schnittstelle auch so dokumentiert sein, dass die Kunden sie erfolgreich verwenden können.
Steuert eine Software Maschinen oder Geräte, können die für diese Maschinen und Geräte maßgeblichen Normen auch für die Softwaredokumentation relevant sein. Insbesondere betrifft dies die Gestaltung von Warnhinweisen.
Die Schlüsselbereiche, für die Sie die wichtigsten Best-Practices kennen sollten, sind:
Soll eine hochwertige Softwaredokumentation entstehen, können Sie nicht erwarten, dass ein Entwickler diese Dokumentation ohne entsprechende Vorbildung „nebenbei“ aus dem Ärmel schüttelt.
Wenn Sie keinen Technischen Redakteur einstellen können und keinen auf die Erstellung von Softwaredokumentation spezialisierten Dienstleister beauftragen möchten, bleibt nur eine Lösung: Sie müssen den mit der Dokumentationserstellung betrauten Mitarbeitern das erforderliche Grundlagenwissen vermitteln, damit diese Miarbeiter selbst verständliche, benutzerfreundliche Dokumentation erstellen können.
Wesentliche Verbesserungen können Sie erstaunlich schnell erzielen. Wie in vielen Bereichen gilt auch für Technische Dokumentation die bekannte 80-zu-20-Regel (Paretoprinzip): 80 Prozent einer möglichen Qualitätssteigerung lassen sich bereits mit 20 Prozent der Mittel erreichen. Zwischen einer planlos erstellten Softwaredokumentation und dem 80-Prozent-Niveau liegen bereits Welten!
Beispielsweise vermitteln Ihnen meine Schulungen zum Thema Softwaredokumentation und meine Bücher zum Thema Technische Dokumentation in kompakter Form genau diese wichtigen Best-Practices.
Welches die optimalen Werkzeuge zum Erstellen einer Softwaredokumentation sind, hängt in erster Linie davon ab, welcher Typ von Softwaredokumentation entstehen soll. Für Benutzerdokumentation gibt es eine Reihe kommerzieller Autorensysteme, die oft mit einem WYSIWYG-Editor arbeiten. Zum Erstellen von API-Dokumentation kommen in der Praxis häufig teilautomatisierte OpenSource-Lösungen zum Einsatz. Deren Quelldaten sind meist einfache Text-Dateien in Markdown-Syntax.
Grob lassen sich die Tools zum Erstellen von Softwaredokumentation in folgende Gruppen einteilen:
Übrigens: Ist Ihnen etwas aufgefallen? Word ist nicht unter den aufgeführten Erstellungswerkzeugen. Zwar wird immer noch ein erheblicher Anteil an Softwaredokumentation mit Word geschrieben, das optimale Werkzeug hierfür ist Word jedoch nur in den seltensten Fällen.
Eine sehr umfassende Übersicht mit nahezu allen auf dem Markt verfügbaren Tools zum Erstellen von Softwaredokumentation finden Sie im Tool- und Web-Guide Technische Dokumentation auf www.indoition.com. Ergänzend biete ich außerdem auch Workshops zur Auswahl eines Redaktionssystems an, in denen wir gemeinsam Ihre projektspezifischen Anforderungen analysieren und dann eine Vorauswahl der auf Ihre spezielle Situation am besten passenden Tools treffen. Ich berate Sie dabei vollkommen neutral und frei von jedem Interesse, Ihnen eine bestimmte Software zu verkaufen.
Viele der Erstellungswerkzeuge für Softwaredokumentation unterstützen sogenanntes Single-Source-Publishing. Darunter versteht man, dass aus derselben Textquelle (Single-Source) mehrere Zieldokumente generiert werden können: einerseits mehrere Medien ‒ z. B. ein druckbares Handbuch (PDF) und eine Online-Hilfe (HTML) ‒ andererseits und gleichzeitig auch unterschiedliche Varianten der Dokumentation ‒ z. B. die Dokumentation für eine Standard-Version und für eine Professional-Version derselben Software. In diesem einfachen Beispiel entstünden aus einer gemeinsamen Textquelle am Ende also vier Dokumente: Handbuch zur Standard-Version, Online-Hilfe zur Standard-Version, Handbuch zur Professional-Version, Online-Hilfe zur Professional-Version. In der Praxis sind es oft noch deutlich mehr Dokumente.
Bei der Ersterstellung einer Softwaredokumentation ist der Effizienzgewinn durch das Single-Source-Publishing noch klein, denn hier könnten Sie fast ebenso schnell die Texte einfach auch kopieren. Bedenken Sie aber, dass Sie eine Softwaredokumentation in der Regel auch weiterpflegen möchten. Wenn Sie Texte kopiert haben, müssen Sie später jede Änderung an mehreren Stellen nachpflegen. Mit Single-Source-Publishing machen Sie jede Aktualisierung oder Ergänzung nur an einer einzigen Stelle: der Single-Source. Die Änderung oder Ergänzung wird dann automatisch beim nächsten Generiervorgang in alle Zieldokumente übernommen. Bei größeren Projekten kann das schnell mehrere Tage oder sogar Wochen an Aufwand sparen.
Wenn Sie die Werbeversprechen der Hersteller lesen, erscheint jedes Help-Authoring-Tool das universell beste Erstellungswerkzeug zu sein. Das ist natürlich Quatsch. Ein pauschal für alle Zwecke bestes Tool kann es gar nicht geben. Welches Tool genau für Ihren speziellen Einsatzzweck am besten geeignet ist, bedarf einer individuellen Analyse unter Abwägung aller spezifischen Vor- und Nachteile. Folgende Punkte sollten Sie dabei unbedingt bedenken und prüfen:
Ergänzend zu den Help-Authoring-Tools gibt es noch eine Reihe weiterer Werkzeige, die Ihre redaktionelle Arbeit erheblich vereinfachen und beschleunigen können:
Mein Name ist Marc Achtelig. Ich erstelle seit mehr als 30 Jahren Softwaredokumentation.
Als Berater für Softwaredokumentation und selbstständiger Technischer Redakteur biete ich unter anderem folgende Dienstleistungen an:
Auf meiner Hauptseite www.indoition.com finden Sie ausführliche Informationen zu meinen Dienstleistungen für Softwaredokumentation.
Gerne helfe ich Ihnen auch persönlich weiter. Ich freue mich auf Ihre Nachricht!
Marc Achtelig
