Wie wird Software „richtig“ dokumentiert? Diese Frage wurde mir mit einer Anfrage gestellt, in deren Kern es darum ging, die bestehende Software-Dokumentation dahingehend zu untersuchen, ob die zelebrierte „Leistungsschau der Buttons“ noch zeitgemäß sei.
Wie eine Software zu dokumentieren ist, hängt wesentlich von der Software selbst ab. Eine API (Application Programming Interface) wird sicherlich anders zu dokumentieren sein als ein Buchhaltungsprogramm. Erfahrungsgemäß kommen bei der Dokumentation von Software zwei Strategien zur Anwendung, wobei der Fokus einmal auf der Software und das andere Mal auf dem Nutzer der Software liegt.
Mensch und Maschine
Bei der funktionsorientierten Dokumentation stehen die einzelnen Funktionen der Software im Mittelpunkt. Für die Dokumentation von Programmiersprachen oder APIs ist dies sicherlich der effektivste Ansatz.
Bei der handlungsorientierten Dokumentation dagegen stehen die Aufgaben, die der Nutzer mit der Software durchführen will, im Zentrum des Interesses. Dabei werden die möglichen Aufgaben zuerst analysiert. Danach werden die entsprechenden Aktionen, die mit der Software durchgeführt werden müssen, um die Aufgabe bewältigen zu können, mittels Prozeduren (Handlungsanweisungen) beschrieben. Beschreibende bzw. erklärende Textelemente werden nur soweit wie nötig eingefügt. Diese Vorgehensweise eignet sich insbesondere bei Anwendungssoftware, bei der der Nutzer ein konkretes Ziel verfolgt, z.B. Serienbrief erstellen, Rechnung korrigieren, Prozesse steuern.
Gemischtes Doppel
Tatsächlich findet man den funktionsorientierten Ansatz öfters auch einmal bei der Dokumentation von Anwendungssoftware. Im Extremfall wird dann akribisch jeder einzelne Menüpunkt beschrieben. Alle Menübefehle werden in der Reihenfolge ihres Vorkommens dokumentiert – keine Funktion wird ausgelassen. Diese Vorgehensweise wird häufig deshalb gewählt, um sicherzustellen, dass die Software-Dokumentation „vollständig“ ist, was als wesentliches Qualitätsmerkmal betrachtet wird.
Diese Vorgehensweise ist für Software, bei der sich der Workflow des Nutzers nicht an der Reihenfolge der Menüpunkte orientiert, offensichtlich wenig hilfreich. Die beabsichtigte Leistungsschau („schaut her, wie viel buttons wir haben“) wird vom Nutzer ignoriert – die Software-Dokumentation ebenso.
Steter Tropfen höhlt den Stein
Jedoch kann auch eine handlungsorientierte Dokumentation zunehmend funktionsorientiert werden. Die Ursachen dieses Phänomens sind dann eher schleichender Natur. Zuerst wird für eine neue Software eine handlungsorientierte Dokumentation erstellt. Mit der Weiterentwicklung der Software, initiiert durch Kunden, die sich neue Features wünschen, werden dann ergänzend, mehr oder minder im Hauruckverfahren, die neu hinzu gekommenen Features dokumentiert. Ziel der aktualisierten Dokumentation ist es dann, dem Nutzer das jeweilige neue Feature zu präsentieren (Stichwort: Leistungsschau). Dabei spielt es dann keine Rolle mehr, ob das neue Feature adäquat im handlungsorientierten Kontext dokumentiert ist.
Somit kann das Wissen, wie Software-Dokumentation „richtig“ erstellt wird, durchaus hilfreich sein. Aber es muss auch richtig angewendet werden.