1
Das Schreiben einer Dokumentation für Software
Thomas Matterne
www.matterne.eu
2
Inhalt
Das Schreiben einer Dokumentation für Software .....................................................................
3
Das Schreiben einer Dokumentation für Software
Eine technische Dokumentation ist nicht gleich technische Dokumentation. ...
4
Die Form wahren
Die Darstellungsform der Dokumentation ist ebenfalls ein kleiner Drahtseilakt geworden. Die ersten
Dokus...
5
Navigation gut, da man schnell zum
entsprechenden Teil der Doku
kommt und in der Regel auch eine
Suchfunktion zur Verfüg...
6
Innerhalb der einzelnen Kapitel geht die Struktur weiter, auch hier wäre es ein Fehler einfach
drauflos zu schreiben. An...
7
Was sonst noch dazugehört!
Am Ende einer jeder Dokumentation gehört entweder ein Stichwortverzeichnis oder besser noch e...
Nächste SlideShare
Wird geladen in …5
×

Das Schreiben einer technischen Dokumentation

1.643 Aufrufe

Veröffentlicht am

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

Veröffentlicht in: Technologie
0 Kommentare
0 Gefällt mir
Statistik
Notizen
  • Als Erste(r) kommentieren

  • Gehören Sie zu den Ersten, denen das gefällt!

Keine Downloads
Aufrufe
Aufrufe insgesamt
1.643
Auf SlideShare
0
Aus Einbettungen
0
Anzahl an Einbettungen
131
Aktionen
Geteilt
0
Downloads
3
Kommentare
0
Gefällt mir
0
Einbettungen 0
Keine Einbettungen

Keine Notizen für die Folie

Das Schreiben einer technischen Dokumentation

  1. 1. 1 Das Schreiben einer Dokumentation für Software Thomas Matterne www.matterne.eu
  2. 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. 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. 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. 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. 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. 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.

×