Wie schreibe ich eine gute Dokumentation?

Eine junge Frau steht neben dem Rednerpult und lächelt ins Publikum, das man aber nicht sieht auf dem Bild.

Quelle: Markus Luigs/TYPO3

Dieses Jahr habe ich alleine (ohne eine weitere Person) meinen ersten Vortrag auf den Developer Days gehalten. In den sechs bis sieben Wochen vor den Developer Days habe ich mich sehr intensiv mit den Vorbereitungen für meinen Vortrag auseinandergesetzt. Neben den Erkenntnissen über das Schreiben einer guten Dokumentation habe ich während der Vorbereitung für meinen Vortrag auch einige Erkenntnisse darüber gesammelt, auf was man achten muss, wenn man seine erste Präsentation auf den Developer Days hält.

(Info zu Geschlechtern: Wenn ich von der männlichen Perspektive spreche meine ich auch immer die anderen. Aber es spart Zeit nur von einer Perspektive aus zu schreiben.)

­

Inhalt der Seite

  1. Mein Vortrag: Why documentation? How to write good documentation!
  2. Tipps für die Vorbereitung eines Vortrags

Why documentation? How to write good documentation!

Zuerst geht es um den Inhalt einer guten Dokumentation für TYPO3 Erweiterungen, also um einen Teil meines Vortrags. Danach geht es um Conveyance , also darum, wie man etwas am besten vermittelt, damit es in einer Dokumentation auch so ankommt, wie es gemeint war. Nach dem Schreiben sollte man den Text noch verbessern. Ich stelle zwei Techniken vor, wie man das macht.

Inhalt meines Vortrags und einer guten Dokumentation

Kriterium für eine gute Dokumentation

Meine Hauptaussage, die ich mit meinem Vortrag rüber bringen wollte war: “Schreibt Dokumentationen und gebt Euch Mühe dabei!“. Und ich wollte vor allem das “Wie mach ich das?” klären. Ich finde es dabei wichtig zu definieren, was genau eine Dokumentation zu einer wirklich guten Dokumentation macht. Sozusagen welches Kriterium muss sie erfüllen oder maximieren, damit man sie als gut definieren kann.

Dieses Kriterium war: “die Fähigkeit des Lesers seine Ziele zu erreichen in allen Anwendungsbereichen und für alle Arten von Lesern” (Quelle: CNCF ).

“The effectiveness of your documentation enhances if you increase the ability of the user to succeed in achieving their objectives within every range of scope and for all users”

Meistens kommt ein Leser oder der Nutzer einer bestimmten Dokumentation mit einem klaren Ziel oder einer konkreten Frage auf die Dokumentation. Dementsprechend ist es sehr hilfreich, wenn er sich schnell orientieren kann, um keine Zeit mit Texten und Passagen zu verschwenden, die ihn nicht zum Ziel führen.

Strukturierung der Inhalte

Nun kann man als Verfasser der Dokumentation unterschiedliche Probleme haben. Zum Beispiel kann man schon ein paar Themen und Texte im Kopf haben, aber man weiß nicht, wie man sie strukturiert (Strukturierung). Hier bietet es sich an auf das Model “Darwin Information Typing Architecture“ oder anders ausgedrückt “Themen basiertes Schreiben“ (Quelle: LIOS) von IBM (Quelle: technicalwriterhg ) zurückzugreifen. Es wird als Standard verwendet, um den Inhalt einer Dokumentation effektiv zu organisieren. Jedes Thema lässt sich in einen der drei Container sortieren: Konzepthemen, Aufgabenthemen und Referenzthemen.

“Concept topics, task topics and reference topics”

In meinen Folien findest Du die Definitionen für diese verschiedenen Thementypen und einige Beispiele auf Englisch.

Pflichthemen und Gewichtung

Eine weitere Herausforderung als Verfasser kann es sein, dass man nicht weiß, welche der Themen und Informationen, die man im Kopf hat auch wirklich in (s)eine Dokumentation sollten (Pflichtthemen: was muss rein, was wäre “nice-to-have”). Oder man ist sich nicht sicher wie man die unterschiedlichen Themen in der Dokumentation zueinander gewichten soll (Gewichtung). Zum Beispiel, ob eine Dokumentation vor allem alle Features beschreiben sollte. Und ob man die möglichen Step-by-step Anleitungen, wie man eine bestimmte Aufgabe erfüllt, nur sporadisch hinzufügen kann.

Der Kontext über den wir hier sprechen ist ganz entscheidend. Es müssen ganz andere Themen als Pflichtthemen definiert werden, wenn wir von einer anderen Art von Dokumentation sprechen.

In meinem Falle ging es um die Dokumentation von einer TYPO3 Erweiterung, deswegen nehmen wir das mal als Beispiel. In der Dokumentation einer TYPO3 Erweiterung gibt es zwei Fragen, die meiner Meinung und der von CNCF in einer Dokumentation beantwortet werden müssen:

  1. Ist die Erweiterung eine Lösung für mein aktuelles Problem? (Frage potenzieller Nutzer der Erweiterung)
  2. Wie kann ich die Features der Erweiterung nutzen oder sogar erweitern? (Frage der Nutzer der Erweiterung)

(Quelle: CNCF)

Außerdem sind diese Konzeptthemen pflicht und müssen in eine gute Dokumentation:

  1. Der Zweck der Erweiterung (auch Motivation für das Erstellen dieser Erweiterung)
  2. Die Beschreibung der Architektur
  3. Die Begründung und grafische/textbasierte Aufbereitung der Designentscheidungen

Denn wenn diese Themen gut dokumentiert sind, wird der investierte Zeitaufwand sich mit dem Nutzen, den Verfasser und Nutzer der Dokumentation daraus ziehen, aufwiegen.

Ein mögliches Anfangsszenario, wie ich eine TYPO3 Erweiterung dokumentieren kann ist:

  1. Erkläre wieso diese Erweiterung existiert
  2. Beschreibe für wen diese Dokumentation gedacht ist (am besten teilst Du Deine Dokumentation gleich in unterschiedliche Perspektiven: Developer, Integrator, Redakteur/Editor)
  3. Führe einen Übergang ein, d.h. kläre den Leser darüber auf, was er erwarten kann in den anderen Bereichen der Dokumentation. Also auch in den Bereichen, die die Aufgabenthemen und die Referenzthemen betreffen.

Beispiele dazu findest Du in meinen Folien.

Es ist beim Dokumentieren wichtig darauf zu achten, dass jedes Feature abgedeckt ist. Am besten kann man hierfür ein Konzeptthema eröffnen und jedes Feature einzeln beschreiben. Wenn Du dann weitere Informationen hast, wie eine Step-by-Step Anleitung zur Verwendung des Features, kannst Du dazu einen Übergang einfügen. Dieser Übergang verlinkt das Konzepthema mit dem Aufgabenthema. Oder falls Du eine Referenz zu Kommandos hast, kannst Du auf dieses Referenzthema vom Konzepthema aus referenzieren.

Aber nicht nur jedes Feature sollte beschrieben sein. Genau so wichtig ist es, dass jede mögliche Aufgabe, die ein Nutzer der Erweiterung potenziell ausführen muss, beschrieben ist. Je häufiger der Nutzer diese Aufgabe machen muss, desto wichtiger ist es, dies zu dokumentieren. Die Liste von möglichen Aufgaben kann anfangs noch unvollständig sein. Das ist ganz normal. Um diese Unvollständigkeit besser beheben zu können, sollte man offen für Feedback sein und sich an einen konstanten Arbeitsaufwand für die Dokumentation gewöhnen.

Neue Nutzer

In meinem Vortrag habe ich explizit auch neue Nutzer berücksichtigt. Ich finde diese Gruppe so wichtig, weil neue Nutzer die begeistertsten Nutzer der Dokumentation sind. Deshalb sollte man auf sie ein besonderes Augenmerk legen. Um neue Nutzer an die Hand zu nehmen kannst Du folgende Liste beim Verfassen Deiner Dokumentation abarbeiten:

  1. Zeige den neuen Nutzern, wie sie Deine Erweiterung installieren können
  2. Beschreibe, wie sie Deine Erweiterung konfigurieren können (z.B. Site settings, extension configuration)
  3. Führe aus, wie sie eine einfache Aufgabe zum Laufen bringen, um Deine Erweiterung zu verifizieren (z.B. Datensatz und Plugin erstellen)

Conveyance - wie bringe ich den Inhalt verständlich rüber

Sprechen wir zuerst über das mit Abstand wichtigste Konzept. Ich nenne es das “Scanning principal”. Es geht davon aus, dass jeder Nutzer einer Dokumentation meistens mit einer konkreten Frage im Kopf auf die Dokumentation zugreift. Dann beginnt die Scan-Phase. Der Nutzer überfliegt die Dokumentation. Wenn der Nutzer denkt, dass der Artikel die gesuchten Informationen enthalten könnte, beginnt die nächste: die Lese-Phase. Für die Scan-Phase benötigen wir vor allem eine leicht verständliche Struktur. Für die Lese-Phase benötigen wir vor allem einen roten Faden.

Kommen wir nun zu den wichtigsten Punkten, die eine Dokumentation verständlich machen und für den Leser zeitsparend sind.

  1. Verwende leichte Sprache: Das heißt nicht, dass man nicht auch komplizierte Sachverhalte erklären kann. Vielmehr heißt es, dass man die Informationen auf eine möglichst einfache und fassbare Weise vermittelt und keine stark verschachtelten Sätze verwenden sollte. Dazu gehört auch, die Definition einer Abkürzung beim ersten Erwähnen zu erläutern. (z.B. für was DTO steht)
  2. Passe den Text an den Leser an: Nutze die verschiedenen Perspektiven - Developer, Integrator und Editor, um jeden mit einzubeziehen und gleich nach Zielgruppe zu sortieren. In diesem Zuge ist es auch sinnvoll von seinen Lesern Feedback anzunehmen. Diese können am besten beurteilen, ob die Dokumentation in Bezug auf ihre Zielgruppe und deren damit verbundenen Hintergrund noch angepasst werden muss. Es kann auch sinnvoll sein, einen eigenen Slack Channel zu erstellen, um schnell und unverbindlich auf Fragen zu antworten.
  3. Komme schnell zum Punkt: Keiner von uns hat die Zeit, sich lange mit einer komischen Dokumentation herumzuschlagen. Deshalb setze wichtige Informationen an den Anfang (deutsch: oben - links, arabisch: oben - rechts). Halte Dich kurz und sei klar. Verwende eine Seitenübersicht, die die Themen gleich zu Beginn einmal kurz auflistet. Schon allein das Gefühl von Übersicht gibt dem Leser ein gutes Gefühl.
  4. Vermeide “Weak writing“: Der Text sollte klar, einfach, konsistent und konkret sein und die Perspektive des Lesers im Blick behalten. Dazu kann man einige Tipps nutzen. Z.B. das Verwenden von “active voice” (Aktivform), das Einhalten einer logischen Reihenfolge (von allgemein zu speziell) und das präzise Beschreiben von Sachverhalten. Du findest Beispiele in meiner Folie (weitere Tipps findest Du in Common Mistakes in Technical Writing and How to Avoid them).
  5. Achte auf die Korrektheit der Sprache: In jedem Framework gibt es gewisse Konventionen, an die man sich halten sollte. Generelle Regeln zu TYPO3 Dokumentationen findest Du in unserem Überblick (How to Document main documentation). Um die genaue Schreibweise von unseren Fachbegriffen zu erhalten kannst Du hier reinschauen (Spelling, terms and glossary). In der TYPO3 Dokumentation wird amerikanisches Englisch verwendet. Du kannst aber auch britisches Englisch verwenden.
  6. Bleibe auf dem Laufenden: Gewöhne Dir an, die Dokumentation regelmäßig zu updaten. Immer wenn Du eine Änderung im Code tätigst, gehe Deine Dokumentation durch und update sie.

Techniken, um die Dokumentation zu verbessern

Reversed outlining - nachträgliche Gliederung

Nutze diese Technik, um zu erkennen, wie Du Deine Ideen aktuell strukturierst. Oft schreibt man einfach erstmal drauf los und weiß am Ende nicht, ob die Reihenfolge der Themen in einer sinngemäßen Reihenfolge abgearbeitet wurden. Hier bietet es sich an das nachträgliche Gliedern zu verwenden. Nachträglich, weil man normalerweise davor die Gliederung macht und dann erst den Text schreibt.

Wie gehst Du vor:
  1. Schreibe eine Gliederung Deiner Dokumentation auf ein Blatt
  2. Frage Dich, wie diese Liste beim Leser ankommt. Kann der Leser die Sachverhalte nachvollziehen mit der aktuellen Reihenfolge der Themen? Existieren Lücken, die das Verständnis beeinträchtigen könnten?
  3. Verschiebe die einzelnen Abschnitte so, dass der Sachverhalt leicht verständlich ist. Wenn Lücken existieren, fülle diese mit dem nötigen Inhalt, um die Konzepte besser zu verstehen.

In meinen Folien zeige ich ein Beispiel.

Hier findest Du eine Videoanleitung, wie Du “Reversed Outlining” anwendest.

Text laut vorlesen

Die Technik hilft dabei verwirrende Satzstrukturen und Formulierungen aufzudecken. Außerdem erkennt man dadurch leichter, wo man den Tonfall noch nachbessern muss.

Vorgehen:
  1. Lese die Dokumentation laut vor
  2. Frage Dich, stolpere ich über gewisse Sätze? Fühlen sich die Übergänge von einem Thema ins nächste zu schnell an? Entspricht der Tonfall dem gewünschten Tonfall? Manchmal gibt es dafür Richtlinien an denen man sich orientieren kann. In unserem Framework gibt es aktuell keine Richtlinien für eine bestimmte “Brand voice”.
  3. Schreibe die Sätze so um, dass das vorliegende Problem, z. B. lange verschachtelte Sätze, behoben wird.

Andere Techniken

Weitere Techniken kannst Du hier nachlesen: 4 Proven Techniques for Revising Your Writing.

Das Wichtigste in Kürze

Eine gute Dokumentation beantwortet die Fragen, die Leser haben können. Zur Strukturierung der Dokumentation, kannst Du die Methode “Topic-based writing” verwenden. Wenn Du eine Dokumentation schreibst, lege besonderes Augenmerk auf neue Nutzer, z.B. der TYPO3 Erweiterung, und auf die Perspektive, die der Leser mitbringt. Beachte die Regeln für das Scanning Prinzip. Vermeide einen schlechten Schreibstil (“weak writing”). Halte Deine Dokumentation auf dem aktuellen Stand und sei beim Schreiben und Verbessern der Dokumentation präzise. Wenn Du mit Deiner Dokumentation fertig bist, wende die oben genannten Techniken an, um sie zu verbessern.

Zum Schluss, sei Dir im klaren, dass eine Dokumentation nur Schritt für Schritt richtig gut werden kann. Wenn Du am Ball bleibst und immer mal wieder kleine Änderungen vornimmst, dann näherst Du Dich Deinem Ziel an, eine Dokumentation zu schaffen, die Deinen Lesern die Fähigkeit gibt, alle ihre Ziele zu erreichen – das, was eine gute Dokumentation ausmacht.

Tipps für die Vorbereitung eines Vortrags

Wer dieses Jahr einen Vortrag auf den Developer Days halten wollte, musste das Konzept dazu bis Ende Mai einreichen. Da das Orgateam die Richtung als zu technisch empfand, konnte ich meine geänderte Beschreibung tatsächlich noch Mitte Juni abgeben. Sie meinten, die Entwickler hätten andere Probleme inhaltlicher Natur, die wichtiger für den Vortrag wären. Aufgrund dieser Änderungen ist mein geplanter Teampartner abgesprungen. Also sollte das mein erster Vortrag auf den TYPO3 Developer Days sein, den ich direkt alleine halten musste.

Das Konzept stand also schon mal. Und wenn das Konzept steht und öffentlich ist, dann sollte man sich doch daran halten, oder nicht? 

Zwischen Theorie und Praxis

Ich bin erst in die falsche Richtung gelaufen. Im Hintergrund hatte ich die Frage: “Was gibt es denn schon auf dem Markt zum Thema Dokumentation?“. Ich habe gängige Quellen wie Wikipedia verwendet, um mich zu informieren. Wenn ich in mich gehe, dann hatte ich implizit erwartet dort ein paar gute grundlegende Best Practises zu finden, wie man eine gute Dokumentation schreibt. Aber dem war nicht so. Und als ich dann mitten im Sammeln und Schreiben der ersten Folien war, habe ich gar nicht mehr gemerkt, dass eigentlich ein wichtiger Aspekt fehlt: Die Best Practises! Den Inhalt, den ich in dieser Phase meinem Vortrag hinzugefügt hatte, habe ich im Nachhinein komplett verworfen. Ich wollte nämlich nicht alle unterschiedlichen Arten von Software Dokumentation aufzählen und beschreiben. Erstens war das langweilig und zweitens war die Richtung nicht die, in die es gehen sollte. Sie hat nicht wirklich das behandelt, was eine gute Dokumentation ausmacht. Auf eine gute Quelle bin ich erst gestoßen, als ich Feedback eingeholt habe.

An dieser Stelle möchte ich mich nochmal herzlich für das Feedback von Eike Drost und Chris Müller bedanken. Ohne sie wäre der Vortrag deutlich schlechter geworden.

Dieser Stolperstein hat mich viel Zeit gekostet. Erst durch Feedback habe mich überhaupt getraut sämtliche irrelevante Themen wegzulassen. Vom eingereichten/geplanten Konzept habe ich folgende Themen am Ende gar nicht behandelt:

  • Dokumentationsarten
  • Klassifikation der Dokumentation von TYPO3 Erweiterungen und der offiziellen TYPO3 Dokumentation
  • Gründe für Dokumentation
  • Problem und Bedrohungen durch KI generierter Dokumentation

Ich bin aber froh, dass ich die obigen Themen weg gelassen habe, denn diese Themen hätten nicht wirklich die Fragen beantwortet, die ich mir stelle, wenn es um gute Dokumentation geht.

Was möchte ich Euch hier mitgeben? Meine Hauptaussage ist, dass ich am Anfang des Vorbereitens unvoreingenommen an das Thema Dokumentation hätte heran treten sollen, obwohl es eine öffentliche Timeline gibt. Ich hätte mir zuerst selbst mehr Gedanken machen sollen, was für mich eine gute Dokumentation ausmacht. Und aufgrund meiner daraus entstandenen Fragen, hätte ich dann das Internet durchforsten sollen. Genau das meine ich mit unvoreingenommen.

Meine Best Practises

Wenn ich Best Practises für einen Vortragenden formulieren müsste, der noch keinen fertigen Vortrag im Petto hat und seinen ersten Vortrag auf den Developer Days hält, dann wären das Folgende:

  1. Auch wenn Du eine grobe Struktur und Beschreibung für Deinen Vortrag eingereicht hast: Wenn Du denkst, dass Dein Vortrag signifikant besser wird, wenn Du diese Struktur änderst, dann mach das.
  2. Hole Dir unbedingt von mehr als einem Feedback. Und vor allem früh, denn bis Dein Vortrag richtig gut wird, braucht es genau wie bei Dokumentationen viele Iterationen.
  3. Anstatt Powerpoint würde ich Dir raten revealjs mal auszuprobieren. Dort kannst zu Plain HTML verwenden, um Deinen Vortrag zu gestalten.
  4. Trau Dich! Nächstes Jahr wird es wieder ein “Call for Papers” geben. Und dadurch ersparst Du Dir die Kosten für ein Ticket.  Aber die Kosten sind nicht relevant. Relevant ist die Erfahrung, die Du machst und die ist unbezahlbar. Man geht immer mit neuen Erfahrungen raus und das ist es, was wirklich zählt.

Weiterführende Lektüre

Ich habe auch einen Blogartikel über die Perspektive als Prüfungsbeisitzer bei den TYPO3 Zertifizierungen und über die Coding Night der diesjährigen Developer Days geschrieben. Du findest den Artikel hier: Zu den TYPO3 Zertifizierungen und der Coding Night.

Fazit

Insgesamt war es für mich eine sehr ereignisreiche und schöne Zeit auf den Developer Days. Deswegen komme ich nächstes Jahr gerne wieder mit einem neuen Vortrag. Mal sehen über was ich da reden werde.

Hat Dir der Artikel gefallen?