Beispiele sind die beste Dokumentation

 (rakhim.exotext.com)
38 Punkte von GN⁺ 2025-10-11 | 8 Kommentare | Auf WhatsApp teilen
  • Wenn Entwickler Dokumentation durchsuchen, reichen in 95 % der Fälle einfache Beispiele völlig aus, doch nur in 5 % der Fälle lassen sich in offiziellen Quellen überhaupt Beispiele finden
  • Offizielle technische Dokumentation wird grundsätzlich für Menschen geschrieben, die tief im jeweiligen Ökosystem stecken, weshalb Entwickler, die zwischen mehreren Projekten und Sprachen wechseln, erheblich mentale Energie für die Wiederherstellung des Kontexts aufbringen müssen
  • Betrachtet man die Dokumentation der Python-Funktion max(), ist viel Vorwissen nötig, um die Syntax der Funktionsdefinition und die Konzepte dahinter zu verstehen; mit fünf einfachen Beispielzeilen ist sie jedoch sofort verständlich
  • clojuredocs.org aus der Clojure-Community bietet durch nutzerbeigetragene Beispiele praxisnahe Dokumentation und ist ein vorbildliches Beispiel, das durch die Einbeziehung verwandter Funktionen den tatsächlichen Nutzwert erhöht
  • Selbst große Softwareprojekte stellen nur selten alle vier Dokumentationstypen bereit, weshalb Entwickler nach Tutorials suchen — nicht weil sie Anleitung brauchen, sondern weil sie Beispiele brauchen

Die Bedeutung von Beispielen beim Durchsuchen von Dokumentation

  • Wenn Entwickler nach Dokumentation suchen, reicht in 95 % der Fälle ein einziges Beispiel aus
  • Doch nur in 5 % der Fälle finden sich Beispiele in offiziellen Quellen
  • Die meisten offiziellen technischen Dokumentationen richten sich standardmäßig an Menschen, die tief im Ökosystem verankert sind
  • Viele Entwickler müssen im Alltag mehrere „Welten“ gleichzeitig im Kopf jonglieren
    • Wechsel zwischen Projekten, Sprachen und Frameworks sind häufig
    • Das Wiederherstellen des Kontexts und Verstehen der Situation kostet beträchtliche mentale Energie

Analyse am Beispiel der Python-Dokumentation

  • Beispiel der Funktion max() in der Python-3-Dokumentation
    • max(iterable, /, *, key=None): Gibt das größte Element zurück
    • Danach folgen fünf kurze erläuternde Absätze
  • Python-Wissen, das man kennen muss, um diese Dokumentation zu verstehen
    • die Bedeutung von * in einer Funktionsdefinition
    • die Bedeutung von / in einer Funktionsdefinition
    • das Konzept eines „positional-only parameter separator“
    • das Konzept eines Iterable
    • das Konzept von keyword-only arguments
    • die allgemeine Bedeutung des Parameters key
  • Erst beim Lesen des Textes wird verständlich, welche Werte man übergeben und wie man die Funktion tatsächlich aufrufen muss

Die Wirkung einfacher Beispiele

  • Es wird anerkannt, dass sich wichtige Details nicht einfach zugunsten der Kürze weglassen lassen
  • Dennoch suchen viele Entwickler diese Seite nur auf, um schnell herauszufinden, wie man der max-Funktion eine benutzerdefinierte Sortierfunktion (key) übergibt
  • Mit einem Beispiel wie dem folgenden hätte man sofort die gewünschte Information 
    max(4, 6) # → 6  
max([1, 2, 3]) # → 3  
max(['x', 'y', 'abc'], key=len) # → 'abc'  
max([]) # ValueError: max() arg is an empty sequence  
max([], default=5) # → 5
  • Durch Beispiele ist das leicht und intuitiv zu verstehen

Vorbildliche Praxis aus der Clojure-Community

  • clojuredocs.org ist ein Community-basiertes Projekt aus der Clojure-Welt
    • Nutzer tragen Beispiele zu eingebauten Funktionen bei
    • Im täglichen Programmieren eine unverzichtbare Ressource
  • Beispielseiten: into, spit, map
  • Merkmale dieser Beispiele
    • Sie enthalten nicht nur die betreffende Funktion, sondern auch verwandte Funktionen
    • Das erhöht Praxisnähe und Nutzwert

Die Grenzen heutiger Dokumentation

  • Selbst große Softwareprojekte stellen nur selten alle vier Arten von Dokumentation bereit
  • Warum man zögert, auf den Link „Documentation“ zu klicken
    • Meistens führt er zu knapper, schwer lesbarer, automatisch generierter API-Referenz
  • Der tatsächliche Grund, warum Entwickler nach Tutorials suchen
    • Nicht weil sie Anleitung brauchen, sondern weil sie Beispiele brauchen
    • Tutorials sind nützlicher, weil sie Beispiele enthalten

Verwandte Beiträge

8 Kommentare

 
sonnet 2025-10-12

Ehrlich gesagt scheint das vor allem auf Java und Python zuzutreffen. Das sind auch Ökosysteme, in denen ein starker sprachzentrierter Überlegenheitsanspruch oder eine paradigmatisch isolierte Kultur vorherrscht.
Gemessen an Python passt der Inhalt zwar gut, aber wenn man verschiedene Sprachen lernt, wirken die 5 % doch ziemlich übertrieben.
 
kuber 2025-10-12

Code ist die Dokumentation selbst – kommt zu Golang~
Wir entwickeln auch ohne README, indem wir den Testcode durchsehen.
 
pjtco 2025-10-11

Ich dachte schon, ich wäre der Einzige, der zu dumm ist, die offizielle Dokumentation zu verstehen, haha.
Wenn man einfach ein echtes Beispiel hinwirft und nur ein bisschen dazu erklärt, versteht man es wirklich schnell ...
 
nemorize 2025-10-11

PHP wäre dann wohl zugleich ein gutes und ein schlechtestes Beispiel.

Es ist ein gutes Beispiel, weil man in der offiziellen Dokumentation von Nutzern beigetragene Inhalte hochladen kann und dadurch viele verschiedene Codebeispiele zu sehen bekommt,

...aber auch das schlechteste Beispiel, weil PHP bei den eingebauten Funktionen viele subtile BCs hat und die beigesteuerten Beispiele alle noch aus Uralt-Versionen stammen, sodass sich Dinge darunter mischen, die sich von der tatsächlichen Funktionsweise leicht unterscheiden und die Verwirrung nur noch vergrößern... haha.. ha...
 
savvykang 2025-10-11

Wenn man sich frühere iOS- oder Cocoa-Entwicklungsdokumentationen ansieht, gab es dort einen eigenen Use-Case-Abschnitt; wäre das nicht die richtige Art der Dokumentation? Beispiele, Funktionssignaturen und Erklärungen zum Verhalten werden alle gebraucht.
 
aer0700 2025-10-11

Dass Beispiele die beste Dokumentation sind.

Wenn früher die Schwächen der offiziellen Docs durch Stack Overflow und Googeln ausgeglichen wurden, scheint das heute von LLMs übernommen zu werden.
 
GN⁺ 2025-10-11
Hacker-News-Kommentare

  • Das Beste am alten Python war, dass man beim Öffnen der Bibliotheksdokumentation klar aufgelistete Abschnitte mit Funktionsargumenten und Rückgabewerten hatte. Heute liefern viele Dokumentationen für JavaScript- oder Python-Bibliotheken leider oft nur noch Beispiele. Wenn man schnell etwas bauen will, sind Beispiele gut, aber um Probleme zu beheben oder eine Bibliothek wirklich zu verstehen, sind Erklärungen der Argumente unverzichtbar. Es ist schön, wenn Beispiele ein Bonus sind, aber sie sollten nicht alles sein.

    • Eigentlich willst du Typdefinitionen. Gute Typdefinitionen funktionieren als gute Dokumentation. Werkzeuge für Typsysteme zeigen im Editor oder in der IDE ohnehin schon viele Informationen direkt an, daher muss man seltener selbst Dokumentation nachlesen. Dass es heute mehr beispielzentrierte Dokumentation gibt, liegt an diesem Wandel im Workflow. Man geht davon aus, dass man Informationen, die Typ-Tools ohnehin liefern, nicht noch einmal in die Dokumentation schreiben muss. Wenn ich Dokumentation anschaue, interessieren mich weniger die Details einzelner Parameter als die Frage: „Welches Problem kann dieses Tool für mich lösen?“ Beispiele sind hervorragend darin, genau diese Möglichkeiten zu zeigen. Wenn ich ein konkretes Problem lösen will, kann ich anhand eines Beispiels schnell beurteilen, ob mir das Tool hilft. --- Wenn es ein Typsystem gibt, will ich zuerst Beispiele sehen. Wenn es kein Typsystem gibt, bin ich 1) unzufrieden. 2) will ich zuerst Beispiele sehen und danach Details zu Argumenten/Rückgabewerten/Datenstrukturen.

    • Gute Dokumentation braucht beides. Erst erklärt man die Details, dann ergänzt man verschiedene Beispiele, damit man das Verständnis prüfen kann. Manchmal reichen Beispiele allein aus, aber wenn es zu viele Optionskombinationen gibt, ist es fast unmöglich, alles per Beispiel zu zeigen. Deshalb sollte man zuerst die einzelnen Optionen erklären und dann möglichst viele unterschiedliche Fälle mit Beispielen abdecken, damit Leser sie anwenden können. Und gute Dokumentation zu schreiben ist sehr schwer, und heute sieht man sie wirklich nur noch selten.

    • Ich stimme nicht vollständig zu. Dokumentation im Javadoc-Stil ist Programmierdokumentation auf Basis von Typen und Inline-Docstrings. Sie ist unbedingt nötig, aber dafür muss man nicht unbedingt ins Web gehen — effizienter ist es oft, direkt in den Code zu schauen. Beispiele oder QuickStart-artige Anleitungen sind aber ebenfalls unverzichtbar. Sie senken die Einstiegshürde einer Bibliothek. Nur aus dem Code lässt sich die API-Nutzung nicht leicht erschließen. Früher haben viele Java-Bibliotheken nur Javadoc geliefert, und es war mühsam, weil man nicht wusste, wie man sie tatsächlich verwendet.

    • Für mich sind gut kommentierte Beispiele das Beste. Sie können traditionelle Dokumentation aber nicht ersetzen.

    • Hast du vielleicht bedacht, dass andere Menschen einen anderen Lernstil haben als du? Ich verstehe nicht, warum man sich dagegen sträubt, dass Beispiele Teil der Dokumentation sind. Beispiele verringern die Reibung beim Kontextwechsel in verschiedenen Situationen.

  • Auch Unix-man-Seiten brauchen dringend Beispiele. Normalerweise sind sie nur als Nachschlagewerk für Leute geschrieben, die das Tool ohnehin schon gut kennen, und helfen Anfängern überhaupt nicht. Gute Dokumentation braucht beides.

    • Stimme voll zu. Ich möchte alle Autorinnen und Autoren von man-Seiten daran erinnern, dass es mit EXAMPLE einen konventionellen Abschnitt dafür gibt. Ein Blick in die offizielle man(1)-Dokumentation lohnt sich.

    • Dieses Problem habe ich nie empfunden. Ich fange einfach an, etwas zu bauen, lerne dabei die Befehle oder Begriffe und sehe mir nach und nach Fehlercodes, deren Ursachen und die Bedeutung von Parametern an. Auch ohne Beispiele reicht vollständige Dokumentation aus. Umgekehrt sind reine Beispiele ohne jede Erklärung wirklich das Schlimmste. Was ist das überhaupt für eine Dokumentation, wenn man nicht einmal weiß, was die Parameter sind oder was sie bedeuten?

    • Ich fand es interessant, dass Stack Overflow früher etwas Ähnliches versucht hat. Unter dem Namen Stack Overflow Documentation lief von 2016 bis 2017 eine Beta. Man wollte beispielzentrierte Dokumentation aufbauen, aber das Projekt wurde eingestellt. Die Inhalte aus der Community sind trotzdem weiterhin unter CC BY-SA verfügbar.

    • Schau dir mal cheat.sh an. Ich nutze es direkt in Skripten mit curl cheat.sh/"$1".

    • Ich bin immer wieder überrascht, wie viele man-Seiten tatsächlich Beispiele enthalten. Trotzdem gäbe es noch viel Raum für umfassendere Verbesserungen.

  • Beispiele sind nicht nur für Anfänger oder gelegentliche Nutzer gut. Auch erfahrene Leute brauchen reguläre Dokumentation, also Dokumente mit allen Parametervarianten. Zum Beispiel ist die requests-Dokumentation lästig, weil Google mich immer nur auf Seiten mit Quickstart-artigen Beispielen schickt. Ein HTTP GET kennt jeder, aber andere Optionen, das Verhalten von timeout oder ob raise_for_status 204 ignoriert, sind schwer zu finden. Man braucht beides, aber wenn Entwicklerzeit knapp ist, würde ich zuerst korrekte Dokumentation bereitstellen. requests-Quickstart-Link

    • Mit Beispielen versteht man Verhalten viel leichter als mit Referenzdokumentation. Menschen sind schlecht darin, Namen zu vergeben, Konzepte zu ordnen und gute Dokumentation zu schreiben. Ich habe vor Kurzem noch Stunden verloren, weil ein Parameter nur unter bestimmten Bedingungen funktionierte. Den Code zu verstehen war zu komplex, und selbst ein LLM behauptete fälschlich, der Parameter sei undokumentiert. Am Ende war es am effizientesten, mit Beispielcode das gewünschte Verhalten herauszufinden. Beispiele komprimieren viele wichtige Informationen und erlauben schnelle Verifikation. API-Dokumentation dagegen versucht, alles vollständig abzudecken, ist dadurch schwer zu pflegen und vermittelt oft nicht die Kernpunkte. Und solange etwas nicht klar dokumentiert ist, vertraue ich dem Verhalten einer Bibliothek niemals. Wenn es nicht im README klar gezeigt oder durch Typen festgelegt ist, gehe ich immer davon aus, dass es sich ändern kann. Deshalb schreibe ich aufrufenden Code so defensiv wie möglich.

    • Beispiele sind nicht nur für Anfänger wichtig, sondern für alle. Ein Fünf-Sekunden-Beispiel kann einem die Effizienz von einer Stunde Dokumentation lesen und experimentieren geben. Das gilt besonders für manche git-Dokumentation, aber genauso für Funktionen, die im Kern einfach, aber schwer zu erklären sind. Selbst wenn Entwickler nur eine Sache erstellen könnten, sollten sie genug Spielraum haben, sowohl Beispiele als auch Dokumentation zu liefern. Beides sollte vorhanden sein, außer in ganz offensichtlichen Fällen.

    • Stimme zu. Gute Dokumentation sollte fast das gesamte Verhalten eines Programms klar festlegen, und nur mit Beispielen ist das schwer zu leisten.

    • Man kann beides gleichzeitig haben. Beispiele und technische Dokumentation schließen sich nicht gegenseitig aus.

    • Mit „occasional users“ sprichst du genau das an, was ich meine. Jedes Mal, wenn ich zwischen Projekten, Sprachen und Frameworks wechsle, kostet es erheblichen mentalen Aufwand, den Kontext wiederherzustellen und zu verstehen, in welcher Situation ich bin.

  • Manche mögen über Perl schimpfen, aber die Perl-Dokumentation ist wirklich hilfreich. Es gibt immer früh einen SYNOPSIS-Abschnitt mit sofort nutzbarem Beispielcode. Danach folgen Erklärung, Referenz und weitere Beispiele. Beispiele: bigrat-Dokumentation, Archive::Tar-Dokumentation. Wenn man Projektdokumentation schreibt, lohnt es sich, sich am Perl-Stil zu orientieren. Und dieser Stil ist auch gut dokumentiert.

    • Ich habe Perl Anfang der 2000er benutzt und bin 2014 zufällig wieder dazu gekommen, und es war, als käme alles wieder zurück. Vielleicht liegt es an Larry Walls linguistischer Perspektive und Haltung, aber es bleibt einem eindrucksvoll im Gedächtnis. Nicht wegen mathematischer Präzision, sondern eher, weil es sich wie „ein Gespräch mit einem Freund“ anfühlt.

  • Man braucht beides. Beispiele geben einem sofort ein Gefühl dafür, erleichtern die Integration, und Erklärungen zu Parametern und Konfigurationswerten helfen bei komplexeren Problemen und beim Gesamtverständnis des Tools. Fehlt eines von beidem, ist das wirklich unbequem. Nur bei sehr einfachen Bibliotheken können Beispiele vielleicht alles erklären.

    • Man braucht sowohl Beispiele als auch Referenzdokumentation. Wenn möglich, sollte man zusätzlich eine REPL-Umgebung anbieten. Wenn man Beispiele direkt ändern und testen kann, gleicht das viele Nachteile fehlender Dokumentation aus.

  • Das Diátaxis-Framework zeigt gut, dass es verschiedene Arten von Dokumentation gibt und jede ihren eigenen Zweck hat. Nicht eine davon ist „die beste“, sondern es ist wichtig, dass sie für unterschiedliche Bedürfnisse eingesetzt werden. Offizielle Diátaxis-Website

    • Dieser Hinweis müsste eigentlich ganz oben stehen. Es war etwas frustrierend, dass Diátaxis erst nach so viel Diskussion erwähnt wurde. Ich sehe Beispiele zwar als Kernelement von Dokumentation, aber eher als wichtige „Dokumentationstechnik“ denn als eigenständige „Dokumentationsart“.

    • Genau! Beispiele (oder Tutorials) sind eine Säule der Vermittlung eines Systems. Ich weiß nicht sicher, wer das ursprünglich formuliert hat, aber der Link ähnelt dem des am Artikelende genannten Autors: > „Selbst große Projekte haben selten alle vier Arten von Dokumentation. Deshalb zögere ich manchmal, überhaupt auf den Link ‚Documentation‘ zu klicken.“ Ich mag erklärungsorientierte Dokumentation. Wenn man Struktur und Gründe für das Verhalten versteht, kann man Beispiele und Tutorials leichter aufnehmen. Wenn erfahrene technische Autoren oder Lehrende dieses Gerüst von Anfang an sauber anlegen, ist der Effekt groß. API-Referenzen braucht man dagegen vor allem beim Schreiben von Wrappern oder kompatiblen Implementierungen. Ursprünglich begannen viele Projekte mit internen API-Referenzen, und Dokumentation bedeutete dann, diese nach außen offenzulegen. Siehe das divio-Dokumentationssystem

    • Das Diátaxis-Konzept ist ausgezeichnet. In reale Projekte einzubauen ist aber nicht einfach. Jedes Projekt braucht ein anderes Verhältnis der Dokumentationsarten, und alle Formen auf einer einzigen Website bereitzustellen, ist oft ineffizient. Dieses Verhältnis verändert sich zudem mit dem Wachstum der Community und ihrem Professionalisierungsgrad. Ich wünschte, es gäbe einen praktischeren Ansatz. Dokumentation ist eine schwierige Aufgabe, und hoffentlich gibt es irgendwann bessere Lösungen. Derzeit hängt die Qualität im Wesentlichen davon ab, wie viel Zeit und Fachkenntnis investiert wird — und daran mangelt es meist.

  • Bei Unity und Unreal habe ich dieses Problem ständig. Besonders bei Unreal besteht die Knotendokumentation oft nur aus einem Screenshot des Knotens und dessen Namen, ohne zu erklären, wie man ihn tatsächlich verwendet. Bei Unity suche ich ebenfalls nach Dokumentation, um den korrekten Einsatz einer Funktion zu verstehen, und manchmal steht dort schlicht gar nichts. Wenn möglich, würde ich am liebsten selbst Beispiele zur Unity-Dokumentation beitragen.

    • Die miserable Dokumentation von Unreal ist auch für mich ein enormer Zeitfresser. Dort herrscht so eine Haltung von „der Code ist die Dokumentation“, aber diese „Erklärung per Blueprint-Knoten-Screenshot“ ist wirklich schon fast lächerlich.

    • Wegen £JOB frage ich mich immer, ob Leute mit $job wirklich einen bezahlten Job bzw. eine Aufgabe meinen oder ob es einfach nur ein Variablenname ist. An diesem Punkt gerät mein Weltbild ins Wanken.

  • Ich benutze oft ImageMagick und habe deshalb immer nach Beispielen gegoogelt. Also habe ich meine persönlichen Notizen in einer kleinen Sammlung von Befehlsbeispielen zusammengeführt. Ich habe auch detaillierte Erklärungen zu den einzelnen Argumenten ergänzt. Anders als in Blogposts, die nur Beispiele enthalten, finde ich, dass Erklärungen ebenfalls dazugehören. Es ist noch ein Entwurf, aber für alltägliche Aufgaben wie Resize, Optimierung oder Layering schon sehr nützlich. Link zu meinen veröffentlichten Notizen

  • Codebeispiele lassen sich als Unit-Tests ausführen, damit die Dokumentation nicht veraltet oder kaputtgeht. Das ist ein Vorteil, den natürliche Sprache nicht bieten kann.

    • Mit dem Fortschritt von LLMs könnte man künftig vielleicht auch versuchen, etwa die Korrektheit von API-Dokumentation zu überprüfen.

  • Radikale Meinung: Wenn sich die Spezifikation einer bestimmten Methode nicht schon aus ihrer Signatur und ein paar repräsentativen Beispielen intuitiv erschließen lässt, dann versucht diese Methode zu viel auf einmal zu leisten. Ich will weder überladene Abstraktionen noch komplizierte Sonderfälle lernen müssen.

    • Das sehe ich anders. Beispiele sind nicht nur nötig, um die Methode selbst zu zeigen, sondern auch um zu zeigen, wie sie mit anderen Methoden zusammenspielt. Selbst wenn sich alles aus der Methodensignatur ableiten ließe, übersieht man leicht wichtige Dinge wie fehlende Konfiguration, Vorbereitungsschritte oder die Verarbeitung des Ergebnisses. Deshalb sind Beispiele unverzichtbar.
 
howudoin 2025-10-11

Im Java-Umfeld und in der objektorientierten Kultur gab es besonders viele bedeutungslose Erklärungssätze und formale Dokumentation, und auch in den Python-Frameworks, die diese Atmosphäre übernommen haben, sind Beispiele auffallend dürftig.

Ein Beispiel für sinnlose Dokumentation
add(left, right) - Addiert den linken und den rechten Operanden

Gerade die wirklich wichtigen Dinge wie die Datentypen der Parameter, mögliche Exceptions oder die Form der Rückgabewerte bzw. die Funktionsweise werden dabei nicht erklärt.

Bei Manpages der C-Sprache reicht dagegen oft schon eine kurze Beschreibung, sodass man die Verwendung zumindest anhand des Funktions- und der Parameternamen erschließen kann.