Benutzer:ThePacker/ Tipps zum Schreiben technischer Bücher

Gliederung eines Buches

Grundsätzlich solltest Du folgende Fragen mit deinem Buch beantworten. In exakt dieser Reihenfolge.

Warum
Was
Wie
Wohin

Gliederung von Kapiteln

Grundsätzlich solltest Du folgende Fragen in deinem Kapitel beantworrten. In exakt dieser Reihenfolge.

Warum
Was
Wie
(wohin)

Gliederung eines Vortrages

Grundsätzlich solltest Du in einem Vortrag diese Fragen beantworten. In exakt dieser Reihenfolge.

Warum
Was
(wie)
(wohin)

Beispielfragen anhand eines Dialogs

Wenn man einen Dialog beschreiben möchte, so lassen sich im Prinzip diese vier Fragen (Warum, Was, Wie, Wohin) auch auf jeden beliebigen Dialog anwenden. Entlang dieser Fragen solltest Du Dich beim schreiben technischer Dokumente entlang hangeln. Die drei wichtigsten Fragen (Warum, Was und Wie) solltest Du für den Leser immer wieder in der gleichen Reihenfolge beantworten, sodass dieser ggf. Abschnitte überspringen kann, die er aktuell nicht benötigt und nicht unangenehm überrascht wird, weil doch eine Information woanders steht als erwartet. (Principle of least surprise / Prinzip der geringstmöglichen Überraschung).

Warum - Motivation

Warum sollte man / soll der User den Dialog öffnen?
- In einem Satz beantworten - Welchen Grund hat jemand diesen Dialog zu öffnen.
- Was möchte man erreichen - Welche Auswirkung hat der Dialog
- Wie heißt der Dialog
- Wie öffne ich den Dialog - Wie erreiche ich diesen Dialog - Im Zweifelsfall einen Screenshot anbieten

Was - Beschreibung (Sätze oft im Passiv / Aktiv ebenfalls möglich)

Was ist im Dialog im Screen shot zu sehen?
Was bedeuten einzelne Abschnitte im Dialog
Was tun einzelne eingabefelder / Buttons
- Vorgehen, von links oben nach rechts unten oder entlang der optischen Gliederung im Dialog
- Bei möglichen Missverständnissen einen Screenshot anlegen
- Pro abschnitt im Dialog einen Text-Paragraphen vorsehen

"Dieses Feld zeigt die Anzahl der ..."

Wie - Tutorial (Sätze im Aktiv)

Wie benutze ich den Dialog?
Wie kann ich bestimmte Einstellungen vornehmen? (Mögliche Eingabewerte beschreiben / welche werte sind gültige eingabewerte)
Wie hängen bestimmte Einstellungen miteinander zusammen - Wenn sie miteinander zusammenhängen?
Wie kann ich den Dialog beenden / verlassen - falls das nicht offensichtlich sein sollte?

"Klicken Sie dazu auf den Button "Eigenschaften..." ...
"Geben Sie hier die Anzahl der gewünschten ... ein."
"Öffnen Sie die Auswahlliste um ... zu .... ."
"Tragen Sie in das Feld Ihren Namen ein... ."

Vermeiden von Phrasen / Fehlern

Grundsätzlich gilt:

Der Leser entscheidet in welcher Reihenfolge er ein bestimmtes technisches Buch liest.
- Ihr wisst nicht, wie der Leser an die jeweilige Stelle gelangt ist, welche sich der Leser gerade durchliest
  ein paar Möglichkeiten
  - Zufälliges Blättern
  - eine Suchmaschine
  - das Glossar
  - das Inhaltsverzeichnis
  - Oder ihn hat eine bestimmte Grafik aufmerksam gemacht und er liest nun einfach den Text drum herum

Das bedeutet:

Vermeide Phrasen wie,
- "in diesem Abschnitt behandeln wir" - Einfach den kompletten Satz streichen und statt dessen hart in das Thema einsteigen.

Vermeide Zusammenfassungen in einem neuen Kapitel, über das letzte Kapitel
- "Im letzten Kapitel haben wir", "Im letzten Kapitel wurde erläutert, dass" - Einfach weglassen
- -> Das verhindert nämlich, dass du das Buch sozusagen refaktorieren / umstellen kannst

Vermeide es in Kapiteln die Kapitelstruktur zu erläutern, (es sei denn, sie ist enorm wichtig - ist sie meistens nämlich nicht).
- -> Das verhindert, dass du Teile des Textes, der sich plötzlich doch an der falschen Stelle befindet, verschieben kannst.
- -> Das verhindert, dass du Themen weglassen kannst und Du statt dessen Text umschreiben musst, den du eigentlich schon für fertig hälst.

Vermeide es der gleichen Sache der Abwechslung wegen unterschiedliche Begriffe zuzuordnen - es wird nur schwerer verständlich
Benutze für die gleiche Sache / den geichen Sachverhalt immer den gleichen Ausdruck