Der seltsame Abstand zwischen Entwicklern und offizieller Dokumentation

Zwischen Entwicklern und offizieller Dokumentation gibt es immer einen seltsamen Abstand

„Ist es, weil ich nicht gut genug bin, dass ich die Dokumentation nicht verstehe?“ Ich habe das lange Zeit so geglaubt.

1. „Ich glaube, nur ich verstehe es nicht“

Frameworks, Bibliotheken, REST‑APIs, Cloud‑Services… Heutzutage ist die meisten Dokumentation gut geschrieben. Das Problem ist… ich verstehe sie nicht.

Als Anfänger dachte ich so.

„Ah… Ich bin noch nicht gut genug. Wenn ich mehr lerne, wird diese Dokumentation irgendwann flüssig zu lesen sein…“

Also lese ich fleißig. Aber dann:

Ich verstehe die Prinzipien nicht
Ich bin mir unsicher, wo das Konzept endet und wo die Praxis beginnt
Ich habe den Inhalt gelesen, aber beim Schreiben von Code komme ich nicht weiter
Warum ist die Dokumentation so umfangreich?

Jetzt bin ich zumindest ein Entwickler, der nicht mehr „Anfänger“ heißt. Doch wenn ich neue Bibliotheksdokumentation sehe, kommt mir immer noch dieser Gedanke.

„Wow… noch einmal anfangen…“

Ich weiß jetzt, dass es nicht nur an meiner mangelnden Fähigkeit liegt.

2. Dokumentation wird meist aus der Sicht des Erstellers geschrieben

Der Hauptgrund, warum Dokumentation schwerfällt, ist, dass sie meist aus der Perspektive des Erstellers geschrieben ist.

Der Ersteller kennt bereits
die interne Struktur
die Gründe für das Design
die Einschränkungen
wo und wie die Funktion aufgerufen wird
Deshalb enthält die Dokumentation oft
„Diese Methode nimmt diese Parameter“
„Sie gibt diesen Typ zurück“
„In diesem Fall wirft sie eine Ausnahme“
„Damit kann man das Folgende tun“

Das Problem: Wir sind nicht der Ersteller des Programms.

Wir fragen uns typischerweise:

„Wo fange ich an?“
„Welcher Teil der Dokumentation hilft mir bei meinem Problem?“
„In welchen Situationen ist diese Option wirklich nötig?“
„Wann wird diese Codezeile tatsächlich aufgerufen?“

Doch die Dokumentation sagt:

„Diese Option führt die Aktion foo mit der Strategie bar aus.“

…Dann möchte man einfach erst ein Beispiel ausprobieren.

3. „Meine eigene Dokumentation ist auch schwer zu verstehen“

Das Lustige ist, dass ich selbst Dokumentation für meine eigenen APIs oder Bibliotheken schreibe. Dann schreibe ich sie wieder aus der Sicht des Erstellers.

„Diese Funktion macht X…“
„Dieser Endpunkt nimmt diese Argumente…“
„Er gibt dieses JSON‑Format zurück…“
„Bei Erfolg/Misserfolg ist die Antwort so…“

Und ich denke:

„Ist das nicht schon ziemlich freundlich?“

Die Reaktion meiner Kollegen ist meist:

„Kannst du das nicht einfach mündlich erklären?“
„Es gibt zwar Dokumentation, aber ich frage lieber sofort.“

Noch lustiger ist, dass ich manchmal meine eigene Dokumentation nicht mehr verstehe.

Wenn ich eine alte API wiederverwenden will und die alte Dokumentation öffne:

„Hmm… Ich habe das geschrieben, oder? Warum habe ich das so seltsam erklärt…?“

Dann wurde mir klar:

Dokumentation zu schreiben bedeutet nicht automatisch, dass sie leicht verständlich ist.
Ich habe keine Rechtfertigung, die offizielle Dokumentation zu kritisieren, wenn ich sie selbst nicht verstehe. 😅

4. Es ist normal, dass offizielle Dokumentation anfangs nicht verstanden wird

Jedes Projekt hat mindestens eine Bibliothek oder ein Paket, das man ständig nutzt. Man hält die Dokumentation im Browser fest und öffnet sie immer wieder.

Aber es gibt ein Phänomen:

Beim ersten Lesen: „Was soll das bedeuten…?“
Am Ende des Projekts: „Ah, das war das, was ich meinte…“

Und ich frage mich oft:

„Habe ich das nicht schon gelesen? Warum verstehe ich es jetzt?“

Warum passiert das?

Um die Dokumentation zu verstehen, braucht man Erfahrung und Kontext.
Um diese Erfahrung zu sammeln, muss man zumindest versuchen, etwas zu bauen.

Kurz gesagt, man braucht die Dokumentation, um die Dokumentation zu verstehen – ein seltsamer Kreislauf.

Deshalb denke ich jetzt:

„Offizielle Dokumentation ist nicht sofort verständlich. Sie wird erst nach mehreren Projekten und Wiederholungen klar.“

Also ist es normal, dass man sie nicht sofort versteht. Es liegt nicht an dir, sondern an der Struktur.

5. Nicht‑englische Entwickler haben einen zusätzlichen Schwierigkeitsgrad

Wir haben zusätzlich die Herausforderung, nicht‑englische Entwickler zu sein.

Wir können die englischen Sätze lesen.
Wir kennen die technischen Begriffe inzwischen ziemlich gut.
Wir lesen gerne Bücher und Artikel, also fehlt uns nicht das Leseverständnis.

Trotzdem wird uns beim Lesen der offiziellen Dokumentation das Gehirn schneller müde.

Das liegt nicht an mangelnder Fähigkeit, sondern daran, dass:

Englisch selbst einen kontinuierlichen „kognitiven Aufwand“ erfordert
Und zusätzlich
neue Konzepte
unbekannte API‑Designs
abstrakte Beispielcodes
alles gleichzeitig

Das bedeutet, wir verbrauchen mehr Energie als andere, um denselben Inhalt zu verstehen.

Wenn du also fragst: „Warum fällt es mir so schwer, die Dokumentation zu lesen?“

„Ich bin bereits mit einem Handicap unterwegs.“

6. Aber wir haben ein paar Überlebensstrategien

Hier sind ein paar Tipps, die ich beim Schreiben gelernt habe.

6‑1. Das „Alles von Anfang bis Ende lesen“‑Verlangen ablegen

Offizielle Dokumentation wirkt wie ein „Handbuch + Wörterbuch“.
Sie ist nicht wie ein Einsteiger‑Tutorial, das man von Seite 1 bis Ende liest.

Deshalb gehe ich so vor:

Ich schaue mir nur die „Getting Started / Quickstart / Tutorial“ an.
Den Rest behalte ich für
Suche
Fehlerbehebung

6‑2. Zuerst mit Beispielen verstehen, dann die Erklärung lesen

Ich schreibe ein Stück Code.
Ich erhalte einen Fehler.
Ich suche den Fehlertext und lese die Dokumentation erneut.

Dann wird der Text plötzlich klarer:

Beim ersten Lesen: „Ich verstehe das nicht…“
Nach ein paar Fehlversuchen: „Ah, das war der Fehler, den ich hatte…“

Fehlererfahrung macht die Dokumentation zu einer Geschichte.

6‑3. „In meiner eigenen Sprache notieren“

Da die Dokumentation in ihrer eigenen Sprache geschrieben ist, mache ich mir Notizen:

„Wenn diese Option true ist, entspricht das im Wesentlichen dem XXX‑Modus.“
„Diese Funktion ist wie eine Fabrik, die X erzeugt.“
„Merke: Diese Zeile muss immer so verwendet werden. Tieferes Verständnis später.“

Wenn ich später meine eigene „Dokumentation“ wiederhole, habe ich ein solides Set aus offizieller Dokumentation und meinen Notizen.

7. Du bist nicht schuld

Wenn du bis hierher gelesen hast, hast du wahrscheinlich auch schon einmal an der offiziellen Dokumentation geharrt.

Mehrfaches Lesen ohne Verständnis
Ein Abschnitt, den du gestern gesehen hast, heute wiederfinden musst
Nur nach der Lösung des Problems verstehst du den Text

Erinnere dich immer daran:

Du bist nicht allein.
Viele gute Entwickler kämpfen damit.
Sogar Leute, die die Bibliothek täglich benutzen, suchen öfter nach Stack Overflow oder GitHub‑Issues als nach der offiziellen Dokumentation.

Offizielle Dokumentation ist von Natur aus schwer. Das ist nicht deine Schuld.

Wir tun einfach:

Wenn wir nicht verstehen, lesen wir erneut.
Wenn wir immer noch nicht verstehen, schreiben wir Code.
Wenn wir scheitern, schauen wir wieder in die Dokumentation.
Und irgendwann verstehen wir: „Ah, das war der Grund, warum die Dokumentation so geschrieben ist.“

Das ist ein Teil des Lebens als Entwickler.

Also sag ich jemandem, der heute frustriert ist:

„Du machst nichts falsch. Du bist einfach auf dem Weg, die Dokumentation zu verstehen.“

Wir alle sind noch immer verwirrt vor der Dokumentation, haben viele Tabs offen und suchen die Seite, die wir gestern gesehen haben. Trotzdem läuft das Projekt weiter und wir lernen jeden Tag ein bisschen mehr Code. 🙂