Eine kurze Anleitung zum Verfassen einer technischen Dokumentation für Software.

1. 1
Das Schreiben einer Dokumentation für Software
Thomas Matterne
www.matterne.eu

2. 2
Inhalt
Das Schreiben einer Dokumentation für Software ............................................................................. 1
Thomas Matterne................................................................................................................................ 1
www.matterne.de............................................................................................................................... 1
Das Schreiben einer Dokumentation für Software.............................................................................. 3
Immer an den Leser denken................................................................................................................ 3
Die Form wahren................................................................................................................................. 4
Nicht einfach drauflos schreiben......................................................................................................... 5
Die Struktur planen ............................................................................................................................. 5
Tipps & Tricks für die gute Doku ......................................................................................................... 6
Was sonst noch dazugehört!............................................................................................................... 7

3. 3
Das Schreiben einer Dokumentation für Software
Eine technische Dokumentation ist nicht gleich technische Dokumentation. Es gibt wie in jedem
Genre auch hier die ein oder andere Unterform: So zum Beispiel die Programmierdokumentation,
eine Installationsdokumentation, die Datendokumentation, eine Testdokumentation, eine
Entwicklerdokumentation und das klassische Handbuch. Da ich vorwiegend an einem Handbuch für
ein Content Managementsystem arbeitete, konzentriere ich mich in der Folge auf das sogenannte
Handbuch. Zweifellos auch die am weitesten verbreitete Form einer Dokumentation.
Gerade in diesem Fall erfüllt die technische Dokumentation einer grundlegend kommunikativen
Funktion, der technische Redakteur ist im Grunde eine Art Übersetzer. Es hat nämlich Gründe,
warum der Entwickler selbst besser keine Dokumentation für den Endnutzer schreibt. Um es
schmeichelhaft auszudrücken, dazu weiß er einfach zu viel und neigt deshalb etwa dazu zu viel
wegzulassen. Im Grunde spricht er aber vor allem meist eine komplett andere Sprache und merkt das
am Ende nicht einmal.
Immer an den Leser denken
Eine Softwaredokumentation benötigt für mich im Grunde zwei Standbeine, das Tutorial und das
eigentliche Handbuch. Damit löst man halbwegs geschickt jenes Problem, dass ein Handbuch im
Grunde doch noch die Eier legende Wollmilchsau sein soll, die sich an alle Typen von Lesern richtet.
Tatsächlich tut sie das natürlich nicht, sondern jeder Anwender ist individuell und so ist auch meine
Lösung letztlich nur eine Vereinfachung:
Abb. 1: Unterscheidung zwischen Tutorial und Handbuch
Die Frage inwieweit man die Tutorials eigenständig veröffentlichen oder innerhalb des Handbuchs
integrieren kann, kann man zum Beispiel davon abhängig machen ob der typische Anwender eher
mit Anfängerkenntnissen an das Programm herangeht. In diesem Fall können Tutorials zur Erklärung
der Grundfunktionen äußerst nützlich sein. Die Alternative besteht darin kleinere Tutorials innerhalb
der jeweiligen Themenkapitel der Dokumentation zu integrieren.
Die Moral der Geschichte: beim Verfassen einer Dokumentation darf der Autor nicht die Macher im
Blick haben und auch nicht sich selbst, sondern er muss immer versuchen an den Leser zu denken. Es
ist entscheidend, dass er sich diesen Blick behält und dabei eine Art Drahtseilakt vollführt: Auf der
einen Seite muss er auf alle Fragen eine Antwort geben können – auf der anderen Seite darf er nicht
zum Spezialisten werden. Denn im letzteren Fall würden die gleichen Probleme auftreten, wie bei
Dokumentation schreibenden Entwicklern. Zudem – je nach Charakter – würde er sich immer öfter
fragen, ja warum verstehen die Trottel das denn nicht ist doch ganz simpel.
Tutorial:
Praktische Beispiele zur Einarbeitung
in das neue Programm.
Handbuch:
Umfassendes Handbuch mit allen
Funktionen der Software.
Anwender ohne
große Vorkenntnisse
Anwender mit
unterschiedlichen
Vorkenntnisse

4. 4
Die Form wahren
Die Darstellungsform der Dokumentation ist ebenfalls ein kleiner Drahtseilakt geworden. Die ersten
Dokus waren dicke und fette Handbücher, Microsoft hat hier Pionierarbeit geleistet. Aber inzwischen
liegt auch bei Windows kein dickes Buch mehr bei. Daraus aber den Schluss zu ziehen, dass die
lineare, buchartig aufgebaute Dokumentation am Ende ist, ist auch nicht ganz richtig. Jede
Dokumentation braucht auch diese Form, in der Praxis meist als PDF. Das liegt nicht nur daran, dass
sich viele Leute auch heute noch bei der Arbeit mit Dokumentationen gerne nebenbei per Hand
Notizen machen wollen.
Grundsätzlich können wir zwischen Online- und Printdokumentation unterscheiden:
Online-Dokumentation:
- Die Online-Dokumentation muss am Endgerät zur Verfügung stehen, auf dem die Software
genutzt wird. Allerdings auch, anders als der Name vermuten lässt, ohne dabei eine
Internetverbindung herstellen zu müssen.
- In der Regel besteht dabei eine sogenannte Produktkoppelung, also die Dokumentation ist in
der Software selbst integriert. Das kann zum Beispiel auch in Form eines sogenannten
Wizzard1
sein.
- Diese Form der Dokumentation ist gestückelt, d. h. sie ist kontextsensetiv und wenn der
Nutzer an einer bestimmten Stelle des Programms die Doku öffnet, findet er auch nur den
dafür interessanten Abschnitt.
- Das die Dokumentation interaktiv ist, versteht sich von selbst – hoffentlich.
Print-Dokumentation:
- Die Print-Dokumentation wird linear (quer-)gelesen, also immer von oben nach unten.
- Sie bietet den Vorteil besser mit Notizen des Users umgehen zu können. (Es sei denn Ihr
Dokuprogramm bietet diesbezüglich eine gleichwertige Lösung, aber das glaube ich nicht.)
- Generell gilt auch heute noch, dass die Lesbarkeit von Daten auf ausgedrucktem Papier nach
wie vor besser ist als am Monitor.
- Sie eignet sich besonders für Einsteiger gut zum Stöbern und auch als Vorbereitung für die
Nutzung und das Kennenlernen der Software.
Hier noch ein kleiner zusätzlicher Vergleich:
Onlinedokumentation Printdokumentation
Lesbarkeit schlecht, vor allem für lange
Textpassagen ungeeignet
gut, auch für längere Texte die
richtige Wahl
Verfügbarkeit mittel, ist an das Produkt und
dessen Endgerät gekoppelt
gut, das Handbuch kann man sich
auch mal mit nach Hause nehmen.
Schnelle Hilfe gut, da die gesuchte Information
gleich neben dem Problem zu
finden ist
mittel, es braucht schon eine gute
Struktur, ein Inhaltsverzeichnis und
ein Glossar.
Orientierung mittel, da die aufgerufenen Teile
der Dokumentation für sich alleine
stehen.
gut, da die Dokumentation
umfassend informieren kann.
1
Ein bekannter Wizzard war zum Beispiel die Büroklammer von Word.

5. 5
Navigation gut, da man schnell zum
entsprechenden Teil der Doku
kommt und in der Regel auch eine
Suchfunktion zur Verfügung hat.
schlecht, es gibt nur ein
Inhaltsverzeichnis und wer schnell
eine Antwort sucht, muss gut
querlesen können.
Aktualität gut, da die Dokumentation mit
jedem Update der Software
aktualisiert werden kann.
mittel-gut, wenn kein gedrucktes
Handbuch mitgeliefert wird, sondern
ein PDF steht die Doku der
Onlinedoku in nichts nach.
Extras Interaktivität, auch die Einbindung
von Videos ist zum Beispiel
möglich.
Der Leser kann sich Notizen machen,
wichtige Passagen unterstreichen
usw.
Tab. 1: Pro und Contra von Online- und Printdokumentationen
Am Ende heißt es aber wie bereits angedeutet nicht „Entweder – oder“, sondern eben „sowohl, als
auch“. Beide Methoden haben ihre unschlagbaren Vorteile und von den meisten Nutzern werden
auch beide gewollt, der Rest will die eine oder andere Methode – das nimmt sich also nicht viel.
Entscheidend ist am Ende übrigens auch, und hier liegt einer der Gründe, warum das gedruckte
Handbuch nicht mehr in Mode ist, die Distribution der der Dokumentation. Finden Sie einen Weg,
damit der User immer die aktuelle, zum Stand seiner Software passende Version der
Dokumentation hat!
Nicht einfach drauflos schreiben
Im Folgenden geht es hauptsächlich um das Schreiben eines Handbuchs, wobei Handbuch in erster
Linie als Synonym für das zur Software mitgelieferte PDF steht.
Zunächst einmal gilt es Grundlegendes zu klären, nämlich welche Funktionen ein Handbuch
eigentlich erfüllen soll. Nun, machen wir es kurz:
Ein Handbuch soll es dem Anwender ermöglichen,
- das Programm zu nutzen,
- den Leistungsumfang des Programms zu erkennen,
- das Programm richtig einsetzen
- und auch bei Anwendungsfällen, die nicht in der Dokumentation stehen, handlungsfähig zu
sein.
Und das alles sollte vom Umfang her der Software angemessen sein.
Die Struktur planen
Soweit zum Grundsätzlichen, jetzt zum Detail. Die Dokumentation zu einer Software sollte ein
strukturiertes und in einem PDF natürlich auch mit Links versehenes Inhaltsverzeichnis haben. Die
Struktur ist etwas, über das es sich vor dem Start Gedanken zu machen lohnt. Legen Sie fest, welche
Teile ihrer Software jeweils ein Kapitel ausmachen sollen. Das hängt wesentlich vom Umfang der
Software ab. Ein umfangreiches Programm kann nach den einzelnen Modulen gegliedert werden,
kleinere Programme auch nach Anwendungsfällen. Im Zweifel sollte man sich in den Leser versetzen
und sich die Frage stellen, was er braucht. Ist der Endnutzer jemand, der einzelne Module nutzen
kann, ohne dabei etwas über die anderen Teile wissen zu müssen? Das spricht für ein Kapitel nach
Modulen geordnet.

6. 6
Innerhalb der einzelnen Kapitel geht die Struktur weiter, auch hier wäre es ein Fehler einfach
drauflos zu schreiben. An den Anfang eines jeden Kapitels gehört eine kurze Zusammenfassung um
was es hier geht. Und im Folgenden lohnt es sich, eine immer gleiche Struktur zu haben. Diese kann
zum Beispiel durch die dringend empfohlene Trennung zwischen einem normalen Anwender und
einem ITler/Admin entstehen. Hier eine fixe Struktur zu geben ist relativ schwer, deshalb nur ein
Beispiel.
1. kurze Zusammenfassung des Kapitelinhaltes
2. Beschreibung der Eingabemasken
3. Praktisches Beispiel
4. Mögliche Fehler(meldungen) und Lösungen
5. Schnittstellen, mögliche Eingriffe in den Programmcode usw.
Tab. 2: Mögliche Kapitelgliederung
Tipps & Tricks für die gute Doku
Der Ton macht bei einer guten Dokumentation die Musik, auch hier braucht es einen guten Stil beim
Schreiben. Allerdings handelt es sich hier nicht um große Literatur, die Sprache muss nicht zu trocken
sein, sie sollte aber durchaus fachlich und sachlich sein.
Den Anwender direkt ansprechen kann zur Auflockerung nicht schaden, es unterstützt den Verfasser
auch dabei sich immer an das Wesentliche zu erinnern: Die Dokumentation ist für den Anwender
geschrieben!
Der Aufbau sollte flach, einfach und übersichtlich sein. Lange Textwüsten sind kontraproduktiv, es
mag nicht schön sein, aber der Satzbau der BILD-Zeitung ist hier gar nicht so schlecht. Zudem sollten
die wichtigsten Informationen zusätzlich in Grafiken untergebracht werden, so können sie dem Leser
noch leichter vermittelt werden. Grafiken erzeugen beim Leser Aufmerksamkeit und was er dort
liest, merkt er sich wesentlich leichter, als den gleichen Inhalt innerhalb eines längeren Absatzes.
Wer lange Textwüsten vermeidet, lernt auch schnell, dass ein Abschnitt nur ein Thema zum Inhalt
haben sollte. Mehrere Themen können den Leser überfordern, gerade wenn sie komplex sind. Wenn
es gar nicht anders geht, dann überlässt man es am besten dem Leser zu entscheiden – dafür wurden
Querverweise erfunden. Nur ein Thema abzuhandeln kommt auch der schlichten Tatsache entgegen,
dass der User in der Dokumentation oft die Antwort auf ein ganz konkretes Problem sucht.
Hier ein paar weitere Tipps:
 Die wichtigsten Informationen stehen am Anfang des Abschnittes bzw. des Kapitels.
Schlüsselbegriffe stehen weit vorn im Satzbau.
 Häufig nachgefragte Inhalte stehen vor den seltener nachgefragten.
 Standardprobleme stehen vor Spezialfällen.
Man erkennt ein System, nicht wahr?
Zuletzt noch ein paar Worte zur Terminologie. Achten Sie darauf, dass die in der Dokumentation
verwendeten Bezeichnungen auch denen in der Software entsprechen. Diese Begriffe sind konsistent
zu verwenden. Auf der anderen Seite können mit Blick auf die schlechte Suchfunktion innerhalb eines
PDFs in der jeweiligen Branche übliche Synonyme nicht schaden. Nicht jeder Leser sucht gezielt nach
dem, was Sie geschrieben haben.

7. 7
Was sonst noch dazugehört!
Am Ende einer jeder Dokumentation gehört entweder ein Stichwortverzeichnis oder besser noch ein
Glossar, das die entsprechenden Begriffe definiert und es dem User so erspart virtuell oder im
echten Leben die entsprechende Seite anblättern zu müssen. Auch hier gilt die etwas schwammige
Aussage, dass das Glossar dem Umfang der Software angepasst sein muss. Bei der Auswahl des
Inhaltes sollte der Blick wieder in Richtung Leser gehen, was der Programmierer oder der Vertriebler
in einem Glossar stehen haben möchte, interessiert oft weniger. Grundsätzlich sollten Sie hier kurz
die Hauptmodule ansprechen und vor allem Begriffe erklären, die in der Dokumentation an
verschiedenen Stellen immer wieder auftauchen, ohne jedes Mal explizit erklärt zu werden.
Ebenfalls recht sinnvoll kann eine Liste der FAQs sein, der am häufigsten gestellten Fragen. Diese
Liste stellt am besten der verantwortliche Support zusammen, der relativ schnell heraushaben wird,
was nicht nur einen Anwender interessiert. Ganz nebenbei ist der Support auch eine hervorragende
Quelle für die stetige Verbesserung der Dokumentation.
Ein kleines Zuckerl für ihre Anwender könnte auch ein für den Druck optimiertes Sheet sein, das zum
Beispiel eine Reihe von Shortcuts enthalten kann.
Besonders wichtig ist auch das Changelog der Software. Die Dokumentation muss immer auf dem
Stand der Software sein, mit der sie ausgeliefert wurde. Das heißt wer Ihr Programm 1.3 nutzt,
braucht auch die Doku 1.3 usw. Allerdings änderst sich mit jeder neuen Version natürlich das ein
oder andere, diese Änderungen sind im Changelog verzeichnet. Auf diese Weise hat der User die
Möglichkeit zum Beispiel zu sehen, was sich zur letzten Version geändert hat.