Es gibt zahlreiche Gründe, warum Technische Dokumentation schlecht sein kann: fehlender Input oder der Input kam nicht rechtzeitig, keine Standards fürs Schreiben, fehlendes oder mangelhaftes Qualitätsmanagement, nicht die passenden Tools, fehlendes Know-how im Allgemeinen usw. usf. Aber es gibt auch Ursachen für schlechte Technische Dokumentation, deren Ursprünge zunächst einmal dafür gesorgt haben, dass gute Technische Dokumentation erstellt wurde.
Funktionsdesign, Terminologiedatenbank und Dokumentenvorlagen: alles war vorhanden zu Projektbeginn. Die bestehende Dokumentation war wie aus dem Ei gepellt, auf dem neuesten Stand der Technik. Makellos.
Ziel des Projektes war es, eine neu erstellte Software zu dokumententieren. Über die Software konnten unterschiedliche Endgeräte konfiguriert und überwacht werden. Die Anzahl der Aufgaben, die mit der Software vom Benutzer ausgeführt werden konnten, waren durchaus überschaubar. Vor allem ging es darum, dass der Benutzer die notwendigen Konfgurationsmöglichkeiten in der Software findet, damit er dann die richtigen Einstellungen vornehmen kann. Keine komplizierte Sache also, auch nicht sehr umfangreich.
Damit auch nichts schief gehen konnte, wurde mir eine Dokumentenvorlage vorgeschlagen, die für die zu dokumentierende Software am geeignetsten erschien. Somit waren die besten Startvoraussetzungen gegeben.
Meine Vorgehensweise besteht in der Regel darin, zunächst die Struktur für die neu zu erstellende Dokumentation auszubrüten und dann ein oder mehrere Tasks zu schreiben, die für die Funktionsweise der Software bzw. für eine Softwarefunktion wesentlich sind. Hier, oder besser gesagt, erst hier bemerkte ich, dass das Funktionsdesign und die Terminologiedatenbank für die umfangreiche Dokumentation der Geräte und Maschinen des Kunden konzipiert war. Nicht für Software.
Wenn es aussieht wie eine Ente, watschelt wie eine Ente und quakt wie eine Ente, dann sollte es auch eine Ente sein.
Zahlreiche Vorgehensweisen wurden in dem Funktionsdesign naturgemäß anders geregelt, als sie für Software-Dokumentation üblich sind, wobei die folgenden beiden Aspekte herausgegriffen seien:
- die Verwendung von Grafiken,
- die Struktur einer Handlungsanweisung sowie die Anrede des Nutzers.
Insbesondere der Einsatz von Grafiken unterscheidet sich bei der Technischen Dokumentation für Geräte und Maschinen grundlegend von der, wie Grafiken in der Software-Dokumenation eingesetzt werden. Bei der Technischen Dokumenation für Geräte und Maschinen ist eine Grafik häufig das erste Element eines Kapitels/Unterkapitels. Eine Legende ermöglicht die Identifzierung der einzelnen Elemente des Geräts oder der Maschine. Danach folgt die Handlungsanweisung mit den identifizierten Elementen. Eine Struktur, wie sie in der Software-Dokumentation praktisch nicht zur Anwendung kommt.
Bei der Handlungsweisung für ein Gerät oder einer Maschine wird zuerst der identifizierte Gegenstand genannt und dann, was mit ihm zu tun ist. Bei der Software-Dokumentation kommt zuerst das Verb (z.B. klicken, öffnen, speichern) und danach folgt das Objekt (z.B. Menüeintrag), mit dem die Aktion ausgeführt wird. Ein weiterer wesentlicher Unterschied besteht zudem darin, dass der Nutzer einer Software-Dokumentation direkt angesprochen wird, bei Technischer Dokumenation für Geräte und Maschienen in der Regel jedoch nicht.
Nun kann natürlich die Dokumentation für die Software gemäß den Vorgaben, wie sie in dem Funktionsdesign für die Geräte und Maschinen festgelegt sind, erstellt werden. Immerhin wird damit sichergestellt, dass eine gut strukturierte und konsistente Dokumentation produziert wird. Es war auch die erste Software, die dokumentiert werden musste (weil ein Kunde des Kunden dies verlangte, nicht weil der Kunde das wollte) und ein neues Funktionsdesign oder Style Guide zu erstellen, speziell auf die Software-Dokumentation ausgerichtet, dafür schien der Aufwand nicht gerechtfertigt.
So entstand eine Techische Dokumentation, die Software wie eine Maschine beschrieb. Keine wirklich schlechte Technische Dokumentation, aber auch keine wirklich gute Technische Dokumentation. Aber auf jeden Fall keine Software-Dokumentation. Möglicherweise wird sich der Endkunde gefragt haben, was er denn tatsächlich erhalten hat.