next up previous contents
Next: 9.3 Weitergehende Information Up: 9. Technisches Schreiben Previous: 9.1 Anforderungen

Unterabschnitte

9.2 Vorgehen

Ähnlich wie bei Software kann man auch bei technischer Dokumentation eine produktorientierte oder eine prozeßorientierte Sichtweise einnehmen. Die produktorientierte wurde im vorherigen Abschnitt verwendet: Im Mittelpunkt stehen erwünschte und unerwünschte Eigenschaften des Dokuments. Diese Betrachtungen stecken zwar ein Ziel ab, geben jedoch nur schwache Hinweise, wie man vorgehen sollte, um zu einem guten Dokument zu kommen.

Im diesem Abschnitt besprechen wir nun die prozeßorientierte Sichtweise des Schreibens, also das Vorgehen. Verblüffenderweise kann man sehr viel von den Vorgehensmodellen der Softwareentwicklung direkt auf das Schreiben übertragen. [LPD91] beschreibt diese Analogie ausführlicher und enthält auch eine umfangreiche kommentierte Liste von Literatur zum Thema Schreiben.

9.2.1 Wie entwickelt man doch gleich Software???

Das Phasenmodell (Wasserfallmodell) der Softwareentwicklung kann man in seinen Einzelteilen recht gut auf die Erstellung technischer Dokumente übertragen. In den folgenden Abschnitten werde ich genau das tun. Anschließend bespreche ich auch noch die wichtigsten Vorgehensalternativen, die vom Phasenmodell abweichen.

Ebenso wie bei der Softwareentwicklung ist es auch beim Schreiben schwierig, eine lineare Abfolge der Schritte einzuhalten. Allerdings ist dies beim Schreiben ein viel geringeres Problem: Wegen der geringeren Strenge natürlicher Sprache im Vergleich zu Computerprogrammen können leichte Schwächen ohne weiteres hingenommen werden und wegen der geringeren Größe des Entwicklungsteams (oft nur eine Person) sind nachträgliche Änderungen schon abgeschlossener Phasen viel einfacher.

9.2.2 Analyse

In der Analysephase wird eine Problem- und Aufgabenbeschreibung erstellt. Diese Texte sind nicht eigentlich Bestandteil des herzustellenden Dokuments, sondern dienen dem Autor zu seiner eigenen Orientierung. Teile der Beschreibungen finden sich jedoch normalerweise später in der Einleitung des Dokuments wieder.

Die Problem- und Aufgabenbeschreibung enthält

1.
Eine Beschreibung des größeren Zusammenhangs, in dem das Dokument angesiedelt ist.
2.
Die Beschreibung des konkreten Problems, das im Dokument behandelt wird.
3.
Die Charakterisierung der Ziele, die das Dokument erreichen soll (z.B. der Information, die es liefern soll).
4.
Eine Begründung, warum und für wen das Dokument wichtig ist.
5.
Die Charakterisierung des Vorwissens der angepeilten Leserschaft.
6.
Eine Auflistung relevanter Randbedingungen: Zeitbeschränkungen, Umfangsbeschränkungen, technische Randbedingungen (Medien etc.), äußere Vorgaben (Standards) für Stil, Organisation oder Format.
Von zentraler Bedeutung in der Analysephase ist die richtige Charakterisierung der Leserschaft, insbesondere ihres Vorwissens. Schreibt man ein Dokument für eine Gruppe von Gleichen, wie es in der Softwareentwicklung häufig vorkommt, so ist dies relativ einfach. In anderen Fällen empfiehlt sich ein zweistufiges Vorgehen: Man nimmt ein Modell eines gewünschten Lesers an und sammelt dann, mit welchen Unterschieden dazu bei der übrigen Leserschaft zu rechnen ist.

9.2.3 Planung

Bei größeren Dokumenten empfiehlt sich die Aufstellung eines Prozeßplans. Das gilt besonders, wenn mehr als eine Person am Dokument schreiben soll. Der Prozeßplan enthält die Zeitplanung und fixiert Entscheidungen im Hinblick auf Rahmenbedingungen wie Softwarewerkzeuge und Versionsverwaltung. Er enthält außerdem eine Liste benötigter Unterlagen sowie eine Beschreibung der Konventionen zur Entscheidung von Zweifelsfällen sprachlicher, inhaltlicher oder textstruktureller Art. Die letzteren beiden Listen müssen während der Erstellung des Dokuments ständig aktualisiert werden und sind insofern Schreibhilfsmittel, die über einen reinen Plan hinausgehen.

9.2.4 Entwurf

Als Entwurfsmethode eignet sich bei Texten das Top-Down-Vorgehen; man stellt also zu Beginn die Liste der Grobabschnitte oder Kapitel auf, etwa so, wie sie später im Inhaltsverzeichnis erscheinen wird. Dann wird schrittweise verfeinert, indem man die Überschriften der Unterabschnitte und eventuell Unter-Unterabschnitte hinzufügt. Das so entstandene Inhaltsverzeichnis bildet quasi den Grobentwurf. Dieser kann nun zu einem Feinentwurf erweitert werden, indem man zu jedem Abschnitt eine Reihe von Stichworten oder -phrasen aufschreibt, die den Inhalt des Abschnitts näher bestimmen.

Bei dieser Vorgehensweise entdeckt man ständig Fehler oder Ungeschicktheiten im Aufbau, die durch entsprechendes Ändern des Entwurfs ausgebügelt werden müssen. Dieses Problem entsteht aus der (im Vergleich zu Software-Entwürfen) relativen Detailarmut des Textentwurfs, durch die Inkonsistenzen erst spät sichtbar werden. Ebendiese Detailarmut ist aber zugleich ein Segen, denn sie macht Änderungen auch sehr leicht durchführbar. Die meisten guten Autoren verwenden das Top-Down-Vorgehen nur als eine Art Gerippe für ihren Schreibprozeß und schreiben in Wirklichkeit weitgehend assoziativ: Der jeweils nächste Entwicklungsschritt wird an dem Abschnitt gemacht, zu dem einem der jeweils letzte Schritt gerade den nächsten sinnvollen Gedanken eingegeben hat. Die Rückkehr zum Top-Down-Vorgehen wird immer dann vorgenommen, wenn eine Lücke in diesem Prozeß entsteht. Die Rückkehr verhindert, sich im assoziativen Durcheinander zu verzetteln.

9.2.5 Implementation

Weniger noch als beim Programmieren läßt sich beim Schreiben eine klare Grenze zwischen Entwurf und Implementation angeben. Durch das Top-Down-Vorgehen geht eine Aktivität fast stufenlos in die andere über. Zumindest muß man aber irgendwann anfangen, die einzelnen Abschnitte ,,endgültig`` auszuformulieren, was eindeutig eine Implementationstätigkeit ist. Egal wie gründlich die Vorarbeiten waren: Stets tauchen dabei noch neue Ungereimtheiten auf. Da paßt hier ein Gedanke nicht ohne Lücke an den nächsten und da wird dort eine Grundlage benötigt, die weiter oben noch nicht gelegt wurde. In diesen Fällen muß der Entwurf entsprechend korrigiert werden, bevor man weiter fortfahren kann. Bei solchen Änderungen erfordert es einige Disziplin, sie tatsächlich auf der entsprechenden Entwurfsebene durchzuführen, anstatt im Text zu flickschustern.

Im Prinzip gilt bei der Implementation das gleiche Spannungsverhältnis von assoziativem und Top-Down-Vorgehen. Allerdings ist hier ein assoziatives Arbeiten zusätzlich erschwert, weil so viele Details beachtet werden müssen. Deshalb sollte der Volltext als Faustregel in ununterbrochenen Arbeitsblöcken geschrieben werden, die mindestens einen ganzen Absatz umfassen.

Es gibt allerdings auch ganz andere Herangehensweisen an die Implementation als die Orientierung am Top-Down-Modell: Bei einer Arbeitsweise, die mit dem Rapid Prototyping verwandt ist, werden zunächst ohne viel Rücksicht auf die Qualität längere Textpassagen mit möglichst wenig Unterbrechungen geschrieben. Danach erst erfolgen Aufräum- und Verbesserungsarbeiten, die den an sich schon vollständigen Text seiner endgültigen Form annähern.

Der genau gegenteilige Ansatz ist mit dem Risikomodell (Spiralmodell) der Softwareentwicklung verwandt: Hier werden zuerst diejenigen Teile bearbeitet, die am schwierigsten und wichtigsten zu sein versprechen. Sie werden sehr gründlich hergestellt und gut ausgefeilt, bevor darauf aufbauend andere Teile in Angriff genommen werden.

Beim Ansatz mit Wiederverwendung steht am Beginn der Texterzeugung der Versuch, möglichst viele benötigte Teile aus früher geschriebenen Texten direkt oder mit Änderungen zu übernehmen. Diese Möglichkeit besteht dann, wenn man mehrere Texte zu engverwandten Themen zu schreiben hat, so daß sich etwa Definitionen oder Erläuterungen von Grundlagen übernehmen lassen. In diesem Fall sind manchmal ganze Abschnitte ohne Änderungen übernehmbar. Ein anderer Fall ist die Wiederverwendung von Textschablonen, d.h. Absätzen oder Abschnitten, in denen ein bestimmter Gedankengang verfolgt wird und die durch die Änderung von Teilsätzen oder Sätzen an das aktuelle Thema angepaßt werden können. Beispiel: Ein Abschnitt über Zweck und Verwendung einer Prozedur X hat die Form Zweck, Vorbedingung, Nachbedingung, Besonderheiten und kann oftmals unabhängig von X die gleichen Formulierungen zur Verbindung dieser Teile verwenden; eventuell gibt es mehrere solcher Bausteine für ähnliche Zwecke, um erstens für Variabilität in der Formulierung sorgen zu können und zweitens für unterschiedliche Fälle eine angemessene Variante bereit zu haben.

Bei Wiederverwendung besteht eine gefährliche Tendenz, daß der erzeugte Text nicht gut seiner Leserschaft angemessen ist, wenn wiederverwendete Bausteine für eine andere Leserschaft geschrieben waren. Außerdem wirkt der Text selten richtig wie aus einem Guß. Wiederverwendung ist deshalb mit großer Vorsicht zu genießen. Bei der Wiederverwendung von Text anderer Autoren (auch aus der eigenen Organisation) sind die Regeln der Fairneß und die Urheberrechtsgesetze zu beachten.

9.2.6 Testen und Überarbeitung

Wenn das Produkt (sprich: Dokument) ,,fertig`` ist, erfolgt ähnlich wie beim Programmieren eine Testphase. Gute Schreiber beginnen damit schon während der Textproduktion und führen viele Prüfungen ständig nebenher oder gelegentlich zwischendurch aus. Beim Testen wird das Dokument auf verschiedenen Ebenen untersucht, um die Einhaltung der Ziele zu überprüfen und ggf. durch Nachbesserung zu erreichen.

Auf der Mikroebene geht es um lokale Eigenschaften des Textes wie

1.
Stimmen Rechtschreibung, Zeichensetzung, Grammatik?
2.
Ist die Wortwahl angemessen?
3.
Sind die Sätze verständlich (Länge, Aufbau) und angenehm lesbar?
Diese Prüfung können alle Personen vornehmen, die ein wenig vom Themengebiet verstehen. Der Autor selbst ist allerdings weniger gut geeignet, weil er für seine eigenen Mikroebenenfehler weitgehend blind ist.

Auf der Makroebene werden die globalen Anforderungen an den Text geprüft. Hierzu werden die Notizen aus der Analysephase herangezogen.

1.
Stellt er sein Thema und seine Ziele klar?
2.
Paßt der Text zu seiner angestrebten Leserschaft (Inhalt, Detaillierungsgrad, Ton)?
3.
Ist der Text seinem Zweck angemessen (Umfang, Inhalt, Aufbereitung, Form)?
4.
Ist die Organisationsstruktur klar ersichtlich?
5.
Ist alle benötigte Information enthalten?
6.
Hat der Gedankengang Lücken?

Für die Effizienz eines Tests ist es wichtig, daß man sich vor seinem Beginn entscheidet, ob man die Mikro- oder die Makroebene prüfen will. Wer beides zugleich versucht, überfordert sich in der Regel und übersieht dann wichtige Schwächen. Bei Prüfungen auf der Makroebene sollte man sich sogar auf einen oder zwei der angeführten Punkte pro Prüfdurchgang beschränken. Die gleichen Anmerkungen gelten analog für das Vorgehen bei der Korrektur der Schwächen.

9.2.7 Wartung

Viele Dokumente müssen über eine längere Lebensdauer hinweg mehrfach angepaßt, erweitert oder geändert werden. Dabei tauchen ganz ähnliche Probleme auf, wie bei der Wartung von Software

1.
Die Entwurfsentscheidungen und der entstandene Entwurf selbst sind nicht gut genug dokumentiert, um bei der Wartung verstanden zu werden. Deshalb zerstört die Wartung allmählich immer mehr von der ursprünglichen Struktur.
2.
Selbst wenn dieser Fall nicht eintritt, werden die Entwurfsbeschreibungen oft nicht ausreichend mitgepflegt. Das gleiche gilt für die Anforderungsbeschreibungen.
3.
Warter haben die Neigung, Änderungen möglichst lokal zu machen. Auch dies schwächt auf die Dauer die globale Struktur.
4.
Eine wohldokumentierte Versions- und ggf. Konfigurationsverwaltung ist notwendig.
5.
Sind mehrere Varianten eines ähnlichen Textes zu pflegen, verstärkt sich das Problem entsprechend.
Die besten Mittel zur Lösung dieser Probleme sind leicht erfaßbare, kompakte und fest an das Dokument gekoppelte Beschreibungen der Anforderungen und des Entwurfs sowie ein möglichst modularer Aufbau der Dokumente, der Zusammenhänge zwischen Teilen so gering wie möglich hält und so explizit wie möglich sichtbar macht.

Anforderungs- und Entwurfsbeschreibungen werden am besten als Annotationen technisch direkt mit ins Dokument integriert (d.h. in die entsprechende Datei, nicht in den Ausdruck). Zusammenhänge, sowohl innerhalb oder zwischen Dokumentteilen als auch zwischen Dokument und obigen Beschreibungen, kann man über technisch verfolgbare und prüfbare Querverweise explizit machen.

9.2.8 Bilder und andere Medien

Die Regel ,,Ein Bild sagt mehr als tausend Worte`` ist zwar auch für technisches Schreiben ein nützlicher Hinweis, muß aber stets mit Vorsicht umgesetzt werden. (Unter ,,Bild`` wollen wir hier jede Art graphischer Darstellung verstehen.)

Zunächst einmal kann in vielen Fällen in der Tat eine sehr große Informationsmenge mit einem Bild transportiert werden, die als Text erheblich mehr Platz verschlungen hätte. Krasse Fälle dieser Art sind aber eher selten.

Allerdings kann man sehr oft mit einem Bild eine gewisse Information erheblich schneller übermitteln, was gerade für technische Dokumentation außerordentlich wünschenswert ist. Insofern sollten Bilder möglichst häufig eingesetzt werden. Dabei sind jedoch zwei Fallen unbedingt zu vermeiden:

Erstens brauchen die meisten Bilder eine Erläuterung, zumindest, wenn mehr als ein ungefährer Eindruck von etwas übermittelt werden muß. Diese Notwendigkeit kann aber den Vorteil des Bildes wieder völlig zunichte machen, wenn die Erklärung entweder zu lang, zu umständlich oder zu verklausuliert ist oder wenn sie sich schwer auffindbar irgendwo im Text versteckt. Eine gute Erklärung sollte sich direkt in der Bildunterschrift unterbringen lassen und möglichst ohne Rückgriff auf den Text verständlich sein. Kriegt man das partout nicht hin, ist wahrscheinlich das Bild überfrachtet. Abbildung 9.1 ist ein abschreckendes Beispiel für ein völlig überfrachtetes Bild (Bitte nicht nach einem Sinn suchen...). \includegraphics[scale=1]{Bild/schreibabschreck1.ps}

Zweitens erzeugt der Druck zum Einsatz von Bildern manchmal die Neigung, triviales in einer Abbildung darzustellen. Davon fühlt sich der Leser oft auf den Arm genommen und versagt dann eventuell dem Rest des Textes die ernsthafte Aufmerksamkeit. Abbildung 9.2 ist ein abschreckendes Beispiel dieser Art. \includegraphics[scale=1]{Bild/schreibabschreck2.ps}

Für Multimedia/Hypermedia-Dokumente gelten weitgehend die gleichen Regeln, wie sie bisher unter der Annahme von Papierdokumenten besprochen wurden:

9.2.9 ,,Goldene Regeln``

Es gibt umfangreiche Sammlungen von Regeln mit dem Ziel, korrektes, gutes, verständliches oder interessantes Deutsch (oder Englisch) zu schreiben. Da diese Sammlungen häufig zu umständlich oder umfangreich sind, gebe ich hier nur eine kleine Zahl von Meta-Regeln, mit denen man aber schon ziemlich weit kommt:

1.
Habe ein Anliegen (neudeutsch: message).
2.
Orientiere Dich an Deinen Lesern.
3.
Schreibe wie Du sprichst und feile das Ergebnis dann aus.
4.
Schreibe nur einen Gedanken pro Satz.
5.
Halte Dich nie sklavisch an einer Regel fest.

Die ersten vier Regeln bilden zusammen den Schlüssel zu interessantem, lesbaren Text: Nur wenn man genau weiß, was genau es ist, das man seinen Lesern sagen will, schafft man es, sich wirklich auf das Wesentliche zu konzentrieren und eine klare Struktur in den Text zu bringen. Und nur, wenn es einem wichtig ist, das ,,rüberzubringen``, was man sagen möchte, schafft man es auch, die Präsentation interessant zu gestalten. Dies sichert das Interesse des Lesers auf der Ebene der Textorganisation. Die dritte und vierte Regel liefern die Methode, mit der man sich auf der Ebene einzelner Sätze vor Unverständlichem und damit Uninteressantem bewahren kann.

Die letzte Regel besagt lediglich, daß keine Regel gut genug ist, um immer zu gelten. Wenn es also einen genügend guten Grund gibt, brich sie! Ohne Augenmaß und Entschlußkraft kommt man bei größeren Vorhaben selten zu befriedigenden Ergebnissen.

../Cartoon/internet_holdout.gif


next up previous contents
Next: 9.3 Weitergehende Information Up: 9. Technisches Schreiben Previous: 9.1 Anforderungen
Lutz Prechelt
1999-04-13