1

Das Schreiben einer Dokumentation für Software

Thomas Matterne

www.matterne.eu

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

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

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

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

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

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.