HOW TO WRITE A GOOD MANUAL (and get beyond RTFM) Know your product!

well-designed product explains itself writers should be part of design team What is it all about? Explain key concepts/ideas AHA-Effect help user structure your thoughts writer = TEACHER first things first Explain a problem and offer a solution (FAQ) users want to perform (basic) tasks, so concentrate on tasks, not just list all possible knobs, buttons, operations or features (pose questions!) sell the product TEST the manual, rewrite it Know your audience! what do they already know? Usually not as much as you think! lamers Make it enjoyable to read! KISS Keep it short and simple keine langen Wrter, keine Hauptwortketten keine substantivierten Verben no bindewrter no long, complicated sentences not too many no incomplete sentences no technical terms, foreign words use figurative language and common words (paint a picture, bildhafte Vergleiche) no passive voice no tiny fonts/pictures no-nos (yes!) keine Verneinungen use illustrations number points/steps Design: Supply a paper manual (anti-piracy) 2 books (Preface goal of manual, Getting started/Troubleshooter, Main manual, maintenance, legal warnings, FAQ, index) include storage for manual/cheat sheet-sticker more DOs than DONTs The number of readers is inversely proportional to the square of the length of the document

2 Verben sind das Rckgrat des Satzes. In Informatiktexten wimmelt es von Substantiven, die auf -ung, -heit, -keit oder -tion enden. Sie sind mit schuld daran, wenn Fachtexte trocken und behbig wirken. Wenn Sie solche Substantive ab und zu durch die Verben ersetzen, aus denen sie entstanden sind, gewinnen Ihre Texte an Kraft und Dynamik: Statt: Deshalb besteht der nchste Schritt in der Erstellung einer kohrenten Klassenbibliothek. Schreiben Sie: Deshalb geht es im nchsten Schritt darum, eine kohrente Klassenbibliothek zu erstellen. Und noch ein Hinweis: Gehren auch Sie zu denen, die Konzepte in Vorschlag bringen und Probleme einer Lsung zufhren, Manahmen ergreifen und Umstrukturierungen in Erwgung ziehen? Kurz und knapp heit es: vorschlagen, lsen, etwas unternehmen, erwgen. 3 Weniger ist mehr. Befreien Sie Ihre Texte von Fllwrtern, Brokratendeutsch und sprachlichem Bombast. Ihre Texte gewinnen an Frische, Ihre Leser verstehen Sie schneller Statt: Die Merkmale besitzen Gestaltungsrelevanz fr die Menstruktur, die Benutzungssichtendefinition sowie den Dialogablauf. Schreiben Sie: Die Merkmale wirken sich aus auf die Gestaltung der Menstruktur, der Benutzungssichtendefinition und des Dialogablaufs. Prgnanz fngt brigens schon bei der Wortwahl an: Statt Betrachtungsweise schreiben Sie Betrachtung, statt Problemstellung schreiben Sie Problem, statt der EDV-technologische Bereich schreiben Sie die EDV. 4 Mit Vorsicht zu genieen: Anglizismen. Egal, was man von Anglizismen halten mag: Kein Informatiker kommt ganz an ihnen vorbei. Einfach, weil es oft keine brauchbaren deutschen Begriffe als Alternative gibt. Die unbefriedigende Faustregel kann deshalb nur heien: so wenig Anglizismen wie mglich, aber so viele wie ntig. Die Grenze des Zumutbaren ist sptestens berschritten, wenn deutsche Wrter nur noch als Fllmaterial fungieren: All-in-One-Intelligenz. PC Power mit ThinkPad-Feeling. Das Internet ermglicht eine effektive Akzeptanz-Kontrolle aller Teile einer Site ber das Tracking des User-Verhaltens. 5 Leserfreundliche Komposita. Wie Anglizismen sind Komposita ein Teil der Informatiksprache. Sie zu dechiffrieren, ist allerdings mhsam. Setzen Sie deshalb alles daran, zusammengesetzte Wrter zu vermeiden oder zu entschrfen. Mglichkeiten dafr gibt es genug: Stutzen Sie Eigeninitiative auf Initiative zurecht; schreiben Sie statt Werkzeugunabhngigkeit besser Unabhngigkeit der Werkzeuge; unterteilen Sie Multimediaunternehmen in Multimedia-Unternehmen. 6 Kurz allein gengt nicht. Am schnellsten verstehen wir normalerweise Hauptstze mit hchstens 16 Silben das ist etwa Bildzeitungs-Niveau. Schreibende Informatiker sollten sich, was die Satzlnge anbetrifft, besser an der Nachrichtenagentur dpa orientieren: Sie legt die Grenze des Erwnschten mit 20 Wrtern fest, die des Erlaubten mit 30. Wie verstndlich ein Satz ist, hngt aber nicht nur von seiner Lnge, sondern vor allem von seiner Komplexitt ab: den Nebenstzen, Einschben, Verschachtelungen und der Wortstellung. Hier mssen Sie ansetzen, wenn Sie bersichtliche Stze schreiben wollen. Ein Beispiel: Heute kann sich jeder Bankkunde von jedem Ort in der Bundesrepublik via Modem die Informationen, die er bentigt, um bestimmte Finanzdienstleistungen selbst zu ttigen, ins Arbeitszimmer holen. Der Ausgangssatz ist nicht nur 27 Wrter lang, sondern darber hinaus auch noch verschachtelt. Das fhrt dazu, da die beiden Hlften des Verbs kann ... holen durch 52 Silben voneinander getrennt sind. Viele Leser werden sich am Satzende nicht mehr so recht an den Anfang erinnern knnen. In der berarbeitung nimmt der Text Rcksicht auf die Begrenzungen des Kurzzeitgedchtnisses: Jeder Bankkunde kann heute bestimmte Finanzdienstleistungen selbst erledigen. Die Informationen dafr holt er sich via Modem ins Arbeitszimmer von jedem Ort in der Bundesrepublik. 7 Aktiv ist besser als Passiv. Es lt sich fter vermeiden, als sie denken: das leidige Passiv, das vielen Informatiktexten auch noch den letzten Rest Lebendigkeit nimmt. Dabei kostet es so gut wie keine Mhe, mglichst oft im Aktiv zu schreiben. Statt: Der Zugang zum Internet wird kontinuierlich gnstiger. Schon heute werden von Anbietern wie z.B. Cityweb lediglich Preise von 6, DM im Monat berechnet. Schreiben Sie: Der Zugang zum Internet wird immer gnstiger. Schon heute berechnen Anbieter wie Cityweb nur 6, DM im Monat.

8 Immer schn der Reihe nach. Chronologische Informationen schreibt man logischerweise in der Reihenfolge nieder, in der sie sich ereignen. Achten Sie darauf, immer erst das erste Ereignis zu nennen und dann das zweite. Statt: Der schreibende Prozessor sendet, bevor er den Block ndert, ein entsprechendes Signal ber den Bus. Schreiben Sie: Der schreibende Prozessor sendet ein entsprechendes Signal ber den Bus und ndert dann den Block. 9 Pro Absatz ein Gedanke. Ein in sich geschlossener Absatz entwickelt einen zentralen Gedanken. Im Klartext: Ein Thesensatz in Fachtexten ist das meistens der erste Satz nennt das Thema des Absatzes. Alle weiteren Stze des gleichen Absatzes sind Variationen des Hauptthemas. Sie vertiefen den Thesensatz: zum Beispiel durch Definitionen, Begrndungen oder Details. Sehen Sie sich dazu als Positivbeispiel den folgenden Textausschnitt an, der aus Tom DeMarco, Warum ist Software so teuer? (Hanser, 1997) entnommen wurde: GOTOs wurden hufiger eingesetzt, als wir erwartet hatten. In der Pascal-Gruppe fanden wir in immerhin 21 Prozent der Programme GOTO-Anweisungen. Wir haben uns jedes einzelne GOTO angesehen, um nachzuvollziehen, warum sich ein Entwickler fr eine Verletzung der strukturierten Programmiertechnik entschied. Fast alle der 105 analysierten GOTO-Anweisungen waren Not- oder Schleifenausgnge und ... Die Hauptinformation steht im ersten Satz: GOTOs wurden hufiger verwendet als erwartet. Alles folgende ordnet sich dieser Idee unter. Auch Leser, die nur den ersten Satz des Absatzes lesen, bekommen die entscheidende Information mit. 10 Sinn durch Sinnlichkeit. Fachtexte erzielen ihre Wirkung nicht nur durch die reine Informationsvermittlung, sondern auch durch Bilder, Beispiele, Vergleiche oder Ironie. Geschickt gewhlt erfllen solche Leseanreize abstrakte Themen mit Leben und setzen sich im Gedchtnis der Leser fest. Ein Beispiel: Traditionelle Rechnerarchitekturen sind Einzelkmpfer und geraten immer dann ins Schwitzen, wenn es um die gleichzeitige Verarbeitung von einzelnen Aufgaben geht. Teamarbeit ist gefragt. Bei den neuen skalierbaren IBM RISC Rechnern legen sich bis zu 128 Prozessoren gleichzeitig in die Riemen. Allerdings: Solche Sprachbilder entstehen nicht von selbst, nach ihnen mu man fahnden. Dafr aber gewinnen Ihre Texte an Dramatik, berzeugungskraft und Attraktivitt.
Was ist Schreiben? Korrigieren und Arbeiten!

In einem Interview mit dem Magazin, der Samstagszeitschrift des Zrcher TagesAnzeigers, hat der portugiesische Schriftsteller Antonio Lobo Antunes auf die Frage Was ist Schreiben? das Thema auf den Punkt gebracht: Das Wesentliche am Schreiben ist nicht das Schreiben, sondern das Korrigieren. Schreiben ist nur eine Frage des Arbeitens.

Zu guten Texten kommt man, wenn man an seinen Texten arbeitet und feilt Satz um Satz. Ein Beispiel

Ein Hurrikan hat in New Orleans schwere Verwstungen angerichtet. Prfen Sie diesen Satz. Ist etwas falsch daran? Falls ja, was? Wie kann er verbessert werden?

Die Analyse Schwere Verwstungen sind so sinnvoll wie starke Orkane oder ziemliche Katastrophen. Prfen Sie, ob ein Adjektiv ntig ist oder ob es genauso gut gestrichen werden knnte. Verwstungen anrichten ist eine Substantivitis-Konstruktion eine sprachliche Plage. Unter Substantivitis (Nominalstil) versteht man die Verbindung eines Substantivs mit einem bildleeren Verb. Besser ist der Gebrauch bildhafter, aktiver Verben ohne Substantiv. Anrichten kann ein aktives Verb sein. Beispiele: Der Hausmann richtet das Essen an. Es ist angerichtet. Der Terrorist richtet ein Blutbad an. Da hast du etwas Schnes angerichtet. Verwstung lsst keinen Plural zu wie Versandung, Vermehrung oder Verehrung.

Gutes Deutsch ist: Ein Hurrikan hat New Orleans verwstet.