- Co-Autor des Debian-Paketmanagement-Buchs (→ https://dpmb.org)
- Freiberuflicher Redakteur, u.a. für Linux Magazin und Linux User
- Trainer und technischer Autor für die cusy GmbH
Einführung¶
Der Vortrag zeigt euch, wie ihr klarere technische Dokumentationen verfassen und eure technischen Kommunikationsfähigkeiten verbessern könnt. Schließlich erfahrt ihr auch, wie eure Dokumente zugänglicher werden.
Der Vortrag richtet sich an Personen aus den Bereichen
- technische Wissenschaften
- Produktmanagement
- technische Redaktionen
2.1 Überarbeiten eures ersten Entwurfs
2.2 Verwenden eines Redaktionsleitfadens
2.3 Organisieren großer Dokumente
2.4 Illustrieren
2.5 Erstellen von Beispielcode
3.1 Hilfreiche Alternativtexte für technische Diagramme schreiben
3.2 Farbkontraste überprüfen
3.3 Zugängliche Diagramme erstellen
3.4 Barrieren in Dokumenten erkennen
1 Grundlagen des technischen Schreibens¶
1.1 Begriffe richtig verwenden¶
1.1.1 Definiert neue oder unbekannte Begriffe¶
Lernt, Begriffe zu erkennen, die der Zielgruppe nicht geläufig sind.
Wenn ihr einen solchen Begriff entdeckt, wendet folgende Taktiken an:
- Wenn der Begriff bereits existiert, verlinkt auf eine gute Erklärung – Erfindet das Rad nicht neu!
- Wenn der Begriff neu eingeführt wird, definiert ihn
- Wenn in eurem Dokument viele Begriffe eingeführt werden, sammelt die Definitionen in einem Glossar
Verwendet durchgängig dasselbe eindeutige Wort: Wenn ihr eine Komponente einmal Dingsda genannt habt, solltet ihr sie nicht ein anderes mal Dingsbums nennen.
- Bei der erstmaligen Verwendung eines unbekannten Akronyms buchstabiert den vollständigen Begriff und setzt das Akronym in Klammern
- Wechselt nicht zwischen dem Akronym und dem vollständigen Begriff hin und her
- Definiert Akronyme nur, wenn sie wesentlich kürzer sind als der vollständige Begriff und im Dokument häufig vorkommen
Viele Pronomen verweisen auf ein zuvor eingeführtes Substantiv.
Wie Zeiger in der Programmierung neigen auch Pronomen dazu, fehlerhaft zu sein.
In vielen Fällen solltet ihr das Pronomen einfach vermeiden und das Substantiv wiederverwenden.
Manchmal überwiegt jedoch der Nutzen eines Pronomens sein Risiko (wie in diesem Satz).
Wir verwenden folgende Richtlinien für Pronomen:
- Verwendet Pronomen nur, nachdem ihr das Substantiv eingeführt habt
- Setzt das Pronomen so nah wie möglich an das verweisende Substantiv; wenn mehr als fünf Wörter zwischen dem Substantiv und dem Pronomen liegen, solltet ihr das Substantiv wiederholen, anstatt das Pronomen zu verwenden
- Wenn ihr zwischen dem Substantiv und dem Pronomen ein zweites Substantiv einführt, wiederholt das Substantiv, anstatt ein Pronomen zu verwenden
Formuliert die überwiegende Mehrheit der Sätze in technischen Texten im Aktiv.
Wie können Aktiv und Passiv unterschieden werden?
- Beim Aktiv handelt eine Person auf ein bestimmtes Ziel hin:
Person+Verb+Ziel.
- Beim Passiv ist es meist umgekehrt:
Ziel+Verb+Person.
Passive Verben setzen sich meist aus einer Form von sein und einem Partizip Perfekt zusammen.
Beispiele:
wurde interpretiert
wird erzeugt durch
wurde gebildet von
In Sätzen mit Imperativverben werden aktive Personen nicht explizit erwähnt, sondern implizit angesprochen.
Beispiele:
Öffnet die Konfigurationsdatei.
Setzt die Variable
protectedaufFalse
1.4.1 Wählt starke Verben¶
Reduziert ungenaue, schwache oder generische Verben wie die folgenden:
- Formen von sein: ist, sind, waren usw.
- erscheinen
- geschehen
Im folgenden ein paar Beispiele für schwache Verben, die ihr durch starke ersetzen könnt:
Der Fehler tritt auf, wenn ihr auf Senden klickt.
Diese Fehlermeldung kommt, wenn …
Wir sind sehr vorsichtig , um sicherzustellen
- Eine kürzere Dokumentation liest sich schneller als eine längere Dokumentation
- Eine kürzere Dokumentation ist in der Regel leichter zu pflegen als eine längere Dokumentation
- Zusätzliche Dokumentationszeilen bringen zusätzliche Fehlerquellen mit sich
Negativbeispiel:
Die Kornshell (Eigenschreibweise KornShell, auch als
ksh,ksh86,ksh88undksh93bezeichnet) ist ein von David Korn entwickelter Kommandozeileninterpreter wie auch die Beschreibung der Skriptsprache, welche durch diesen Interpreter implementiert wird.
Quelle: Wikipedia: Kornshell
In vielen langen technischen Sätzen steckt eine Liste, die besser in einer Liste gegliedert werden kann:
- wenn die Konjunktion oder in einem langen Satz seht
- wenn ein langer Satz eine Aufzählung enthält
Viele Sätze enthalten Füllwörter, die Platz wegnehmen, die nichts zum Verständnis beitragen.
Beispiele:
zu diesem Zeitpunkt
bestimmt den Wert von
in der Lage sein … zu tun
Listen und Tabellen können vielschichtige Themen ordnen. Wenn sich euer Thema auf eine solche Weise ordnen lässt, solltet ihr euren Text entsprechend umwandeln.
- Aufzählungen werden für ungeordnete Inhalte verwendet, bei denen die Änderung der Reihenfolge nicht die Bedeutung verändert.
- Nummerierte Listen werden verwendet, wenn die Reihenfolge der einzelnen Punkte bedeutend ist.
- Definitionslisten werden verwendet, um Begriffe zu definieren, z.B.:
for- zur Iteration über die Elemente einer Sequenz
while- zur Wiederholung einer Schleife, solange ein logischer Ausdruck wahr ist.
- Verschachtelte Listen werden für hierarchische Inhalte verwendet
Gibt es Ober- und Unterpunkte, so können sich verschachtelte Listen empfehlen. Auch bei der Verschachtelung können die drei Listentypen kombiniert werden.
Nur wenn das Listenelement aus einem oder mehreren Sätzen besteht, solltet ihr Großschreibung und Satzzeichen verwenden.
Tabellen sind geeignet für Inhalte, bei denen jeder einzelne Punkt in ein oder mehreren Kategorien erläutert wird. Achtet bei Tabellen darauf, dass
- jede Spalte aussagekräftig beschriftet ist
- jede Zelle nur wenig Text enthalten darf
- jede Spalte möglichst nur von einem Datentyp sein sollte
Beim Schreiben entwirren wir einzelne Aspekte eines Themas und bringen sie in eine logische Abfolge, die anderen das Thema zugänglich macht.
Der Anfangssatz ist der wichtigste Satz eines jeden Absatzes. Dies hilft beim Querlesen, das Thema des Absatzes zu erfassen ohne alle nachfolgenden Sätze zu lesen. Daher kommt ihm eine besondere Bedeutung zu.
- Ein Absatz sollte eine unabhängige logische Einheit darstellen
- Beschränkt euch in jedem Absatz auf das aktuelle Thema
- Beschreibt nicht, was in einem zukünftigen Thema passieren wird oder was in einem vergangenen Thema geschehen ist
- Streicht bei der Überarbeitung rücksichtslos jeden Satz, der nicht direkt mit dem aktuellen Thema zusammenhängt – oder verschiebt ihn in einen anderen Absatz
Lange Absätze sind visuell einschüchternd. Sehr lange Absätze bilden eine gefürchtete Textwand, die von den Lesenden ignoriert wird. Sie begrüßen im Allgemeinen Absätze mit drei bis fünf Sätzen, vermeiden jedoch Absätze mit mehr als sieben Sätzen. Zieht bei der Überarbeitung in Betracht, sehr lange Absätze in zwei separate Absätze aufzuteilen.
Umgekehrt solltet ihr die Absätze nicht zu kurz gestalten. Wenn euer Dokument viele Ein-Satz-Absätze enthält, ist eure Gliederung mangelhaft. Sucht nach Möglichkeiten, diese Ein-Satz-Absätze zu zusammenhängenden Mehr-Satz-Absätzen oder möglicherweise zu Listen zusammenzufassen.
Gute Absätze beantworten die folgenden drei Fragen:
- Was wollt ihr mitteilen?
- Warum ist es wichtig, dies zu wissen?
- Wie sollte dieses Wissen genutzt werden?
Stellt sicher, dass euer Dokument die Informationen enthält, die euer Publikum braucht, aber noch nicht hat.
Daher solltet ihr
Seriöse Dokumentationsprojekte verwenden viel Zeit und Energie darauf, ihre Zielgruppe zu definieren.
Diese Bemühungen beinhalten:
- Umfragen
- Studien zur Usability
- Fokusgruppen
- Dokumentationstests
- im Software-Engineering
- im nicht-technischen Bereich
- im Forschungsbereich
Schreibt eine Liste mit allem, was eure Zielgruppe lernen soll.
In manchen Fällen sollte die Liste Aufgaben enthalten, die die Zielgruppe ausführen muss.
- Die meisten Personen im Software-Engineering kennen die gängigen Sortieralgorithmen und die Landau-Symbole. Ihr könnt euch also darauf verlassen, dass sie wissen, was
O(n)bedeutet; bei Personen aus dem nicht-technischen Bereich könnt ihr euch jedoch nicht darauf verlassen.
- Ein Forschungsbericht, der sich an medizinisches Fachpersonal richtet, sollte ganz anders aussehen als ein Zeitungsartikel über dieselbe Forschung, der sich an ein Laienpublikum richtet.
- Die Vorlesung über einen neuen Ansatz maschinellen Lernens für Studierende mit Hochschulabschluss sollte sich unterscheiden von derjenigen, die für Studierende im ersten Studienjahr gehalten wird.
- Schreibt eine Liste mit allem, was Eure Zielgruppe lernen soll, um Ziele zu erreichen
- Beachtet, dass eure Zielgruppe manchmal Aufgaben in einer bestimmten Reihenfolge bewältigen muss
- Konzentriert eure Liste auf die Informationen, die eure Zielgruppe lernen sollte
Eure Erklärungen sollen die Neugier eures Publikums befriedigen und nicht eure eigene.
Um die Erwartungen eures Publikums zu erfüllen, benötigt ihr Einfühlungsvermögen.
Um die Dokumentation an euer Publikum anzupassen, gibt es keine einfachen Antworten.
Wir können jedoch einige Parameter nennen, auf die ihr euch konzentrieren könnt:
Achtet auf die Nähe zu eurem Publikum:
- Stimmt das Vokabular auf euer Publikum ab (→ 1.1 Begriffe richtig verwenden)
- Je größer euer Zielpublikum ist, desto geringer wird das gemeinsame Wissen sein.
- Je weniger gemeinsame Erfahrungen ihr voraussetzen könnt, desto mehr müsst ihr erklären.
Wenn ihr beiläufig auf subtile Wechselwirkungen und tief greifende Systeme verweist, werden Neulinge auf diesem Gebiet eure Erklärungen möglicherweise nicht verstehen. Sie können noch nicht an dieses Wissen anknüpfen.
Es gibt einen erheblichen Prozentsatz im Publikum, dessen Erstsprache nicht die Sprache eurer technischen Dokumentation ist.
- Zieht einfache Wörter komplexen Wörtern vor
- Zieht gebräuchliche Wörter seltenen vor
- Haltet eure Texte kulturell neutral
- Verlangt von eurem Publikum nicht, dass sie Feinheiten im Fußball, Baseball oder Sumo kennen, um eure Dokumentation zu verstehen
- Vermeidet Idiome, also Phrasen, deren Gesamtbedeutung von der wörtlichen Bedeutung der einzelnen Wörter in dieser Phrase abweicht, z.B. ein Kinderspiel
- Beachtet, dass einige Übersetzungssoftware verwenden werden, um eure Dokumentation zu lesen.
Ihr könnt Sätze schreiben, ihr könnt Absätze schreiben. Nun sind all diese Absätze zu einem kohärenten Dokument zusammenzufassen.
1. Ein gutes Dokument beginnt mit der Festlegung seines Umfangs.
2. Ein besseres Dokument definiert zusätzlich die nicht behandelten Themen, von denen die Zielgruppe vernünftigerweise erwarten könnte, dass sie in eurem Dokument behandelt werden.
3. Diese Angaben sind nicht nur für euer Publikum, sondern auch für euch von Vorteil: Wenn sich der Inhalt eures Dokuments während des Schreibens von euren Angaben entfernt, müsst ihr entweder euer Dokument neu ausrichten oder eure Umfangsangabe ändern.
- Ein gutes Dokument benennt ausdrücklich sein Publikum
- Neben den möglichen Rollen des Publikums können auch auch die erforderlichen Kenntnisse oder Erfahrungen angeben werden
- In einigen Fällen sollte auch die vorausgesetzte Lektüre oder Kursarbeit angegeben werden
- Ihr könnt nicht erwarten, dass alle Seiten eures Dokuments gelesen werden
- Stellt daher sicher, dass der Anfang eures Dokuments die wichtigsten Fragen beantwortet
- Der Anfang eines Dokuments ist daher am schwierigsten zu schreiben
- Seid darauf vorbereitet, die erste Seite mehrmals zu überarbeiten
Definiert die Bedürfnisse eurer Zielgruppe
- Wer ist euer Zielpublikum?
- Was ist das Ziel der Zielgruppe? Warum lesen sie dieses Dokument?
- Was weiß euer Publikum bereits, bevor es euer Dokument liest?
- Was sollte euer Publikum wissen oder können, nachdem es euer Dokument gelesen hat?
- Wie muss euer Dokument organisiert sein, damit es den Bedürfnissen eurer Zielgruppe entspricht?
Zusammenfassung¶
In den Grundlagen technischen Schreibens behandelten wir:
Zusammenfassung¶
Herzlichen Glückwunsch – ihr kennt nun die Grundlagen technischen Schreibens.
- Wenn ihr die Prinzipien des technischen Schreibens praktisch üben wollt, bieten wir euch einen entsprechenden Kurs an
- Dort behandeln wir auch fortgeschrittene Themen des technischen Schreibens und barrierefreies Schreiben
- Schließlich erarbeiten wir mit euch auch gerne einen Redaktionsleitfaden