|
BASICS
Walter Riemer
walter.riemer@aon.at
GRUNDLAGEN
Wie schreibt man Dokumentationen?
Wie schreibt man
Dokumentationen?
Walter Riemer
1. Überblick
Wenige Leute haben eine Naturbegabung im Schreiben; dementsprechend haben nur wenige Techniker die Fähigkeit, Dokumentationen so zu verfassen, dass sie ihren Zweck wirklich erfüllen, nämlich, einem bestimmten Personenkreis Informationen zu übermitteln, die für ihn von Nutzen sind, ohne dass der Leser einen besonderen Aufwand auf sich nehmen muß, das Geschriebene zu verstehen.
Viel mehr Personen als die „Naturbegabten” sind aber basierend auf entsprechender Schulung durchaus in der Lage, brauchbare Dokumentationen zu verfassen. Ziel dieser Ausarbeitung ist es, diesem Personenkreis entsprechende Hilfestellung anzubieten.
2. Was ist eine Dokumentation?
Eine Dokumentation ist ein (allenfalls auch mit audiovisuellen Mitteln wie insbesondere Bildern oder Zeichnungen angereichertes) Schriftstück, welches einen beispielsweise technischen (oder aber auch aus jedem beliebigen anderen Bereich stammenden) Sachverhalt darlegt.
Jede Dokumentation hat einen objektiven Zweck, nämlich Information an Personen zu übermitteln, die diese Information nicht haben, sie üblicherweise aber benötigen. Eine Dokumentation, die dem Informationsempfänger nicht verständlich ist, verfehlt ihren Zweck; ebenso aber auch eine, die nur mit sehr großem Aufwand seitens des Informationsempfängers verständlich wird, insbesondere aber auch eine, die zwar verständlich erscheint, aber in Wirklichkeit irreführend oder gar falsch ist.
Es gibt Dokumentationen verschiedenster Art:
l Bedienungsanleitungen von Geräten, zum Beispiel Haushalts- oder Elektronik-Geräten.
l Benützerhandbücher für Software, zum Beispiel für Excel.
l Pflichtenhefte, die einem EDV-Auftrag zugrunde liegen.
l (Technische) Berichte, die im Zug einer Projektierung (etwa eines Bauwerks, einer Produktionsanlage oder dergleichen) „”eitend” mitwachsen.
l Schulische Ausarbeitungen wie zum Beispiel Laborprotokolle, Referatsausarbeitungen.
l Diplom- oder Doktorarbeiten.
l Befunde und Gutachten
Die vorstehende Aufzählung sollte nur als am Bereich der Technik orientierte Beispielsammlung gesehen werden; selbstverständlich gibt es Dokumentationen auf allen anderen Gebieten auch.
3. Merkmale einer guten Dokumentation
3.1 Sachlichkeit
Im Vordergrund steht die sachliche Übermittlung eines Sachverhalts. Dokumentationen sind ihrer Natur nach etwas anderes als zum Beispiel Dichtung (nicht nur wegen des von Ihnen erwarteten Wahrheitsgehalts), aber auch etwas anderes als Deutsch-Aufsätze, Liebesbriefe oder Comics.
l Dokumentationen sollen nicht primär unterhaltend sein: persönliche, zur vermeintlichen Auflockerung eingestreute Äußerungen im Stil von „Wer hätte das gedacht?” haben in einer Dokumentation nichts verloren, da sie keinen sachlichen Inhalt transportieren.
l Die Sprache einer Dokumentation soll nicht primär abwechslungsreich sein: für denselben Begriffsinhalt abwechselnd verschiedene Wörter zu verwenden, ist ein grober Fehler. Da der Informationsempfänger sachliche Information erwartet, vermutet er hinter einem anderen Wort zunächst einen abweichenden Begriffsinhalt und muß viel Gedankenarbeit investieren, um vielleicht dahinter zukommen, dass das Gleiche gemeint ist wie weiter oben mit einem verschiedenen Wort. Das Wort „Dokumentation” kommt in diesem Text sehr häufig vor; trotzdem wäre es verfehlt, nur um mehr Abwechslung zu schaffen, das eine oder andere Mal „Ausarbeitung” und dann wieder gar das völlig unspezifische Wort „Arbeit” zu verwenden.
3.2 Gliederung
Das Verständnis wird durch eine gute Gliederung wesentlich erleichtert. Beim Gliedern einer Dokumentation sind zwei Gesichtspunkte zu beachten:
3.2.1 Inhaltliche Gliederung
Die darzustellenden Sachverhalte sollten in logischer, durchschaubarer Weise gegliedert sein, das heißt, in nicht zu große Abschnitte zerlegt sein, die ihrerseits in einer logisch aufbauenden Abfolge stehen.
|
|
Es ist für den Informationsempfänger eine große Hilfe, wenn er am Anfang eine Übersicht über das in der Dokumentation Gebotene lesen kann und in weiterer Folge erst zunehmend tiefer in Details gegangen wird.
l Erstens kann er dadurch leichter entscheiden, ob er die Dokumentation überhaupt lesen soll bzw. auch im Zuge des Durchlesens jederzeit entscheiden, ob er die nachfolgenden tiefergehenden Details überhaupt benötigt.
l Zweitens wird das Verständnis dadurch wesentlich gefördert, dass Schritt für Schritt in größere Tiefe vorgedrungen wird.
Oft ist auch eine am Schluß, eventuell auch am Anfang stehende Zusammenfassung (englisch „Abstracts”) nützlich, die auch mit ausreichend vielen den Inhalt charakterisierenden Stichwörtern formuliert ist, um allenfalls bei Volltextsuche nützlich zu sein (Muster: Inhalt einer diesbezüglichen Karteikarte in einer Bibliothek).
3.2.2 Formale Gliederung
Abschnitte benötigen Überschriften; sind solche ohne Zwang nicht zu finden, müssen die Abschnitte anders gegliedert werden.
International üblich ist heute ein hierarchisch aufgebautes System der Nummerierung von Abschnitten (bzw. deren Überschriften), in dem ausschließlich Zahlen, durch Punkte getrennt, verwendet werden. Ohne weitere Erklärung läßt sich dies aus dieser Dokumentation (dem vorliegendem Text) erkennen.
Gliederungen, die von Groß- und Kleinbuchstaben, römischen Zahlen, Klammern und dergleichen Gebrauch machen, sind international nicht mehr üblich (außer in österreichischen Gesetzen, dort zum Beispiel §5 lit a) ii und dergleichen).
Für untergeordnete Hierarchieebenen ist auch ein Nummerierungssystem in Klammern verbreitet, zum Beispiel so:
(1) obere Ebene
(1.1) darunter liegende Ebene
(1.2) gleichrangige Ebene
(2) obere Ebene
usw.
Verwiesen wird dann zum Beispiel auf Punkt 3.2.2 (1.2).
Eine auf dem Nummernsystem basierende Gliederung bringt neben dem Zwang zu einer systematisch durchschaubaren Darstellung der Inhalte auch noch eine wesentliche Erleichterung bei Bezugnahmen, sowohl aus dem vorliegenden Text selbst als auch gegebenenfalls aus anderen Texten, die auf den gegenständlichen verweisen; dies ist speziell im Bereich von Technik und Wissenschaften allgemein üblich.
Oft geht das Gliederungssystem auch mit Einrückungen von Absätzen einher; dabei sollte jedoch nicht übertrieben werden: man rückt so viel ein, dass die Einrückung deutlich wirksam wird, aber nicht mehr als unbedingt nötig, weil dadurch die Absätze wegen der Begrenzung durch den rechten Rand länger werden und man so Platz am Bildschirm wie auch auf dem bedruckten Papier verschwendet, was der Übersichtlichkeit keineswegs dienlich ist.
Wenn eine Überschrift recht lang ist (wie diese), sollte man sich keineswegs dazu verleiten lassen, die Einrückung des zugehörigen Absatzes zu übertreiben, wie zum Beispiel hier.
Richtig wäre etwa folgendes:
Wenn eine Überschrift recht lang ist
(wie diese), sollte man sich keineswegs
dazu verleiten lassen, die Einrückung des zugehörigen Absatzes zu übertreiben,
wie zum Beispiel im vorhergehenden Absatz.
Auch Blickfangzeichen wie etwa unter Punkt 3.3 sind oft zweckmäßig; der zugehörige Absatz bzw. die zugehörigen Absätze sind angemessen einzurücken.
Einrücken ist etwas anderes, als die erste Zeile eines Absatzes einzuziehen (wie in diesem Absatz): dies ist heute veraltet.
3.3 Vermeiden von Abkürzungen
Abkürzungen sind möglichst zu vermeiden, da sie beim Lesen meist einen gedanklichen Exkurs („was bedeutet diese Abkürzung”) verursachen und damit vom Inhalt ablenken. Davon ausgenommen sind nur einige wenige allgemein übliche und ohne Nachdenken verständliche Abkürzungen wie etwa „usw.” oder „z.B.” .
l
Falls nicht allgemein übliche und bekannte Abkürzungen unumgänglich sind,
müssen sie bei ihrem ersten Vorkommen erklärt werden, zum Beispiel „Hypertext
Markup Language, in der Folge kurz HTML”.
In einer technischen Dokumentation
werden selbstverständlich häufig Abkürzungen unumgänglich sein, insbesondere,
wenn der Zweck unter anderem ist, zur Fachsprache gehörende Abkürzungen
zu vermitteln: dann aber immer mit entsprechender Erklärung beim ersten
Vorkommen.
l Zahlenwörter sind, wenn sie kleine, insbesondere einstellige Zahlen betreffen, auszuschreiben, zum Beispiel „Tres faciunt collegium” (nicht etwa „3 faciunt collegium”). Aussagen wie die vorstehende, die von vornherein nicht unbedingt allgemeinverständlich sind, müssen erklärt werden: „Schon drei Personen genügen, um als Kollegium (Mehrpersonengesellschaft) angesehen zu werden”, nicht etwa „Schon 3 Personen ...”. Besonders störend ist in diesem Zusammenhang die Ziffer 1, zum Beispiel wäre sie in „1 Buch” als „ein” zu lesen, in „1 Orange” aber als „eine”. So etwas führt zur Ablenkung des Lesers vom eigentlichen Inhalt.
|
|
l Ein besonders grober Fehler ist es, aufzählende Zahlen mit Ziffer und Punkt zu schreiben, also zum Beispiel „1. regnete es und 2. war es noch dazu sehr kalt” statt „Erstens regnete es und zweitens ...”. Der Grund liegt darin, dass ein geschriebenes „1.” grundsätzlich auch andere Leseweisen zulässt und der Leser kurz abschweifen muß, um darüber nachzudenken, ob „erstens“ oder „erster“ oder vielleicht so etwas wie „Punkt 1" gemeint ist.
3.4 Sorgfältige Formulierungen
Der Inhalt kann nur durch sorgfältige Formulierung transportiert werden.
l Schlampige Ausdrucksweise resultiert erfahrungsgemäß häufig daraus, dass der Autor selbst nicht so genau Bescheid weiß: wie soll dann erst der Leser den Sachverhalt erfassen können? Das Bemühen um eine sorgfältige Formulierung ist in diesem Fall auch für den Autor selbst von Wert, da es dazu zwingt, den Sachverhalt genau zu durchschauen.
l Schlampige Ausdrucksweise resultiert oft auch daraus, dass der Autor meint, wie man formuliert, ist ja nicht so wichtig; Hauptsache, der Inhalt wird transportiert. Das Letztere ist aber gerade jenes Ziel, das so nicht erreicht werden kann.
Erfahrungsgemäß sind schlampig formulierte, unvollständige Dokumentationen sogar für den Autor in größerem zeitlichen Abstand nicht mehr verständlich; wie sollen sie es dann für einen Außenstehenden sein?
3.5 Gehobene Sprache
Gute Sprache ist eine Voraussetzung (von mehreren) für Verständlichkeit. Das Bemühen um gute Sprache bringt zwangsläufig ein verstärktes Bemühen mit sich, gute Formulierungen zu finden und Disziplin im Aufbau zu praktizieren.
Lockere, umgangssprachliche Formulierungen verleiten den Autor dazu, die Aufgabe des Formulierens selbst schon zu leicht zu nehmen; sie bringen aber auch den Leser dazu, das Gelesene nicht für ganz voll zu nehmen.
Beispiel: ...in Live-Aufnahmen müssen Schrittgeräusche rausgefiltert werden... . Warum müssen sie nicht „herausgefiltert” werden?
Man sollte immer im Auge behalten, daß Sachlichkeit ein wesentliches Merkmal einer guten Dokumentation ist; der Unterhaltungswert spielt keinerlei Rolle!
|
|
3.6 Korrekte Rechtschreibung
Korrekte Rechtschreibung ist nicht Ausdruck von Pedanterie.
l
Texte mit vielen Rechtschreibfehlern machen, jedenfalls bei Lesern, die
die Rechtschreibung beherrschen und darauf auch Wert legen, einen negativen
Eindruck, woraus auch eine negative Beurteilung des Inhaltlichen unwillkürlich
entstehen kann.
So wie ein geschmackvolles Briefpapier oder Firmenlogo ebenso
wie gutes Benehmen der Mitarbeiter zum seriösen Anstrich einer Firma gehört,
lassen auch Texte, die an Rechtschreibfehlern arm sind, auf die Qualifikation
des Verfassers wie auch auf seine Einstellung zu Grundwerten positive Rückschlüsse
zu.
Sich auf die Rechtschreibhilfe des Textverarbeitungsprogramms zu verlassen,
ist ein Armutszeugnis: gerade in technischen Texten macht die Rechtschreibhilfe
meist mehr Arbeit als sie Nutzen bringt, weil sie viele Fachausdrücke nicht
kennt und häufig unsinnige Verbesserungsvorschläge zutage fördert.
3.7 Gute äußere Form
Dokumentationen werden heute praktisch ausschließlich am Computer hergestellt. Die Möglichkeiten der modernen Textverarbeitung sollte man nützen, aber nicht übertreiben:
l Schriften sollten gut lesbar sein (bevorzugt Times, Arial und ähnliche weit verbreitete Schriften). Die Schriftgröße sollte für den Text in der Regel von 10 Punkt bis 12 Punkt sein; Überschriften auch etwas größer (14 Punkt bis höchstens 16 Punkt).
l Mit verschiedenen Schriftarten und auch Schriftgrößen sollte man sparsam umgehen: höchstens zwei verschiedene Schriften und nicht mehr als etwa vier Schriftgrößen verwenden.
l Nach Satzzeichen gehört stets eine Leerstelle (uralte Maschinschreibregel). Sie erleichtert das Erfassen von Sätzen und Satzteilen und damit auch das Erfassen von Inhalten.
l Absätze sollten voneinander durch einen etwas größeren Abstand als den Zeilenabstand (aber nicht durch eine Leerzeile) getrennt sein (dies ist im Texterarbeitungsprogramm einstellbar).
Die erste Zeile eines Absatzes noch etwas einzuziehen ist heute veraltet.
3.8 Schlüssigkeit und Nachvollziehbarkeit
Schlüssigkeit umfaßt die dem Leser eingeräumte Möglichkeit, den aufeinander folgenden Gedanken oder Gesichtspunkten logisch folgen zu können.
Nachvollziehbarkeit umfaßt die dem Leser eingeräumte Möglichkeit, das durch Lesen der Dokumentation erworbene neue Wissen auch selbst anwenden zu können.
Eine gute Dokumentation ist schlüssig und nachvollziehbar. Die Beschreibung einer Laborübung wie im folgenden Beispiel ist weder schlüssig noch nachvollziehbar:
Wir wurden in der Handhabung des Mischpults unterwiesen. Wir nahmen aus einer Rundfunksendung Musik auf MiniDisk auf, wobei zunächst irrtümlicherweise stark übersteuert wurde. Beim zweiten Versuch gelang uns das schon besser ... usw.
Hier erfährt man nicht, welche Einstellungen am Mischpult vorgenommen wurden, um überhaupt das Audiosignal korrekt zu routen (vom Audio-Eingang auf den gewünschten Ausgang zu bringen), was beim Einpegeln falsch gemacht wurde (was vielleicht auch nicht so wichtig wäre), aber auch wie man es richtig macht. Der im zweiten Absatz des Abschnitts 4 beschriebene Informationsempfänger (Mitschüler, der die Übung versäumt hat) könnte die Übung nicht nachvollziehen.
Schlüssig ist der Text deswegen nicht, weil er zusammenhanglos ist. Es ist kein logischer Zusammenhang zwischen den einzelnen aneinander gereihten Mitteilungen des Autors zu erkennen.
4. Für wen schreibt man die Dokumentation?
Beim Verfassen einer Dokumentation ist ständig im Auge zu behalten, an wen sich die Dokumentation richtet, wer also der Informationsempfänger sein soll.
l In Dokumentationen, die in Schulen verfasst werden, ist es eine gute Leitlinie, dass der Informationsempfänger ein Klassenkollege ist, der grundsätzlich auf dem gleichen Wissensstand ist wie der Verfasser der Dokumentation, aber gerade über das gegenständliche Thema nichts weiß (etwa, weil er eine Unterrichtsstunde versäumt hat).
l Dokumentationen, die sich an Außenstehende richten, bedürfen eines besonderen Einfühlungsvermögens des Autors. Eine Bedienungsanleitung für einen tragbaren Kassettenrekorder (Walkman) muß für einen technischen Laien verständlich sein, eine Bedienungsanleitung für ein Oszilloskop wohl nur für jemanden, der sich in der Elektrotechnik oder Elektronik gut auskennt.
Keinesfalls schreibt man eine Dokumentation nur zu dem Zweck, den Leser mit seinem eigenen Wissen zu beeindrucken. Auch eine zu umfangreiche Dokumentation, die etwa für den Leser viel zu weit ins Detail geht, verfehlt ihren Zweck.
|