Ä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.
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.
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
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.
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.
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.
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
Auf der Makroebene werden die globalen Anforderungen an den Text geprüft. Hierzu werden die Notizen aus der Analysephase herangezogen.
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.
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
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.
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...).
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.
Für Multimedia/Hypermedia-Dokumente gelten weitgehend die gleichen Regeln, wie sie bisher unter der Annahme von Papierdokumenten besprochen wurden:
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:
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.