Softwaredokumentation im weitesten Sinne umfasst teilweise sehr unterschiedliche Bereiche. Dies führt oft zu Missverständnissen.
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
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.
Wenn eine hochwertige, professionelle Softwaredokumentation entstehen soll, können Sie nicht erwarten, dass diese Dokumentation ein Entwickler ohne entsprechende Vorbildung mal eben 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!
Die Schlüsselbereiche, für die Sie die wichtigsten Best-Practices kennen sollten, sind:
Beispielsweise vermitteln Ihnen meine Schulungen zum Thema Technische Dokumentation für Software und meine Bücher zum Thema Technische Dokumentation in kompakter Form genau diese wichtigsten Best-Practices.
Welches die optimalen Werkzeuge zum Erstellen von Softwaredokumentation sind, hängt in erster Linie davon ab, welcher Typ von Softwaredokumentation entstehen soll. 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 auf www.indoition.com. Ergänzend biete ich außerdem auch Workshops 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:
Meine Dienstleistungen
Mein Name ist Marc Achtelig. Ich erstelle seit mehr als 25 Jahren hauptberuflich Softwaredokumentation.
Als Berater für Softwaredokumentation und freiberuflicher Technischer Redakteur biete ich unter anderem folgende Dienstleistungen an:
Ausführlichere Informationen zu meinen Leistungen finden Sie bei Interesse auf meiner Hauptseite www.indoition.com.
Gerne helfe ich Ihnen persönlich weiter. Ich freue mich auf Ihre Nachricht!
Marc Achtelig