Anforderungen an Softwaredokumentation
Grundlegende Anforderungen
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:
▶ die Information schnell und ohne Umwege gefunden wird
▶ genau die passende Information gefunden wird, also nichts Irrelevantes mitgelesen werden muss
▶ die Information einfach verständlich ist, also möglichst wenig Denkarbeit geleistet werden muss
▶ die Information auf die eigene Problemstellung angewandt und praxisnah nachvollzogen werden kann
▶ das Lesen schnell geht
Gesetzliche und vertragliche Anforderungen
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.