Les exemples sont la meilleure documentation

• Lorsque les développeurs cherchent dans la documentation, dans 95 % des cas un simple exemple suffit, mais il n’est possible de trouver un exemple dans la source officielle que dans 5 % des cas
• La documentation technique officielle est en général rédigée pour des personnes déjà profondément immergées dans l’écosystème, ce qui exige une énergie mentale importante pour reconstituer le contexte chez les développeurs qui naviguent entre plusieurs projets et langages
• Si l’on regarde la documentation de la fonction max() de Python, les connaissances préalables nécessaires pour comprendre la syntaxe de définition et les concepts de la fonction sont nombreuses, alors que 5 lignes d’exemple permettent de comprendre immédiatement
• clojuredocs.org, dans la communauté Clojure, fournit une documentation pratique grâce à des exemples proposés par les utilisateurs et constitue un excellent modèle en incluant aussi les fonctions associées pour améliorer l’utilité réelle
• Même les grands projets logiciels proposent rarement les 4 types de documentation, si bien que les développeurs finissent par chercher des tutoriels non pas parce qu’ils ont besoin d’être guidés, mais parce qu’ils ont besoin d’exemples

---

L’importance des exemples lorsqu’on cherche de la documentation

• Quand les développeurs cherchent de la documentation, dans 95 % des cas un seul exemple suffit
• Pourtant, il n’est possible de trouver un exemple dans une source officielle que dans 5 % des cas
• La plupart des documentations techniques officielles s’adressent par défaut à des personnes déjà profondément immergées dans l’écosystème
• Beaucoup de développeurs doivent au quotidien jongler mentalement entre plusieurs « mondes »
  • les changements de projet, de langage et de framework sont fréquents
  • reconstituer le contexte et comprendre la situation demande une énergie mentale considérable

Analyse d’un cas dans la documentation Python

• Exemple de la fonction max() dans la documentation Python 3
  • max(iterable, /, *, key=None) : renvoie l’élément le plus grand
  • l’explication se poursuit ensuite sur 5 courts paragraphes
• Connaissances Python nécessaires pour comprendre cette documentation
  • la signification de * dans une définition de fonction
  • la signification de / dans une définition de fonction
  • le concept de « positional-only parameter separator »
  • le concept d’iterable
  • le concept de keyword-only arguments
  • le sens général du paramètre key
• Il faut lire le texte pour comprendre quelles valeurs transmettre et comment appeler réellement la fonction

L’effet d’exemples simples

• On reconnaît qu’il n’est pas possible d’omettre certains détails importants au nom de la concision
• Mais si beaucoup de développeurs arrivent sur cette page, c’est simplement pour trouver rapidement comment passer une fonction de tri personnalisée (key) à la fonction max
• Avec un exemple comme celui-ci, on obtient immédiatement l’information recherchée

  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  
  

• Les exemples permettent une compréhension simple et intuitive

Un modèle dans la communauté Clojure

• clojuredocs.org est un projet porté par la communauté Clojure
  • les utilisateurs y contribuent des exemples pour les fonctions intégrées
  • c’est une ressource indispensable au quotidien pour coder
• Exemples de pages : into, spit, map
• Caractéristiques des exemples
  • ils incluent non seulement la fonction concernée, mais aussi les fonctions liées
  • cela améliore l’utilité concrète et le caractère pratique

Les limites actuelles de la documentation

• Même les grands projets logiciels proposent rarement les 4 types de documentation
  • voir : le système de documentation de Divio
• Pourquoi on hésite à cliquer sur le lien « Documentation »
  • il s’agit le plus souvent d’une référence API auto-générée, concise et difficile à lire
• La vraie raison pour laquelle les développeurs cherchent des tutoriels
  • ce n’est pas parce qu’ils ont besoin d’être guidés, mais parce qu’ils ont besoin d’exemples
  • les tutoriels sont plus utiles parce qu’ils contiennent des exemples

[sonnet]

Honnêtement, j’ai l’impression que cela concerne surtout Java et Python. Ce sont aussi des écosystèmes où le chauvinisme autour de son propre langage ou une culture fortement isolée sur le plan des paradigmes est assez marqué.
Si on prend Python comme référence, le propos tient la route, mais quand on étudie différents langages, les 5 % donnent quand même une impression d’exagération assez nette.

[kuber]

Le code est la documentation : venez chez Go~
Chez nous, on développe en épluchant les tests, même sans README

[pjtco]

Je croyais que j’étais le seul à être trop bête pour comprendre la doc officielle mdr.
Franchement, il suffit de balancer un vrai exemple avec juste un peu d’explication, et on comprend tout de suite…

[nemorize]

PHP serait à la fois un bon exemple et le pire exemple.

C’est un bon exemple dans la mesure où la documentation officielle permet de publier du contenu contribué par les utilisateurs, ce qui permet de consulter divers exemples de code,

...mais c’est aussi le pire exemple, parce que PHP a beaucoup de subtilités de compatibilité ascendante dans ses fonctions intégrées, et que les contributions d’exemples datent toutes de Mathusalem, si bien qu’on y trouve des choses subtilement différentes du comportement réel, ce qui ne fait qu’ajouter à la confusion... lol..

[savvykang]

Dans les anciennes documentations de développement iOS ou Cocoa, il y avait une section de cas d’usage distincte ; n’est-ce pas la bonne manière de documenter ? Il faut tout : des exemples, les signatures de fonctions et l’explication du fonctionnement.

[aer0700]

Les exemples sont la meilleure documentation.

Si autrefois la pauvreté de la documentation officielle était compensée par Stack Overflow et les recherches Google, aujourd’hui ce sont les LLM qui semblent combler ce manque.

[GN⁺]

Avis Hacker News

• Ce qu’il y avait de mieux dans l’ancien Python, c’est que lorsqu’on ouvrait la documentation d’une bibliothèque, on trouvait une présentation claire des arguments des fonctions et des valeurs de retour. Aujourd’hui, beaucoup de documentations de bibliothèques JavaScript ou Python ne proposent plus que des exemples, ce qui est regrettable. Les exemples sont utiles pour construire vite quelque chose, mais pour corriger un problème ou apprendre une bibliothèque, les explications sur les paramètres sont indispensables. Que les exemples soient un bonus, très bien, mais ils ne doivent pas être tout ce qu’il y a

  • En réalité, ce que vous voulez, ce sont des définitions de types. De bonnes définitions de types font office de bonne documentation. Les outils du système de types affichent déjà beaucoup d’informations directement dans l’éditeur ou l’IDE, donc on a moins besoin d’aller lire la doc. Si la documentation centrée sur les exemples se répand aujourd’hui, c’est à cause de ce changement de workflow. L’idée est qu’il n’est pas nécessaire de répéter dans la documentation des informations que les outils de typage fournissent déjà. Quand je consulte une doc, je m’intéresse moins au détail des arguments qu’à la question suivante : « quel problème cet outil peut-il résoudre ? » Les exemples sont excellents pour montrer ces possibilités. Quand je veux résoudre un problème précis, voir un exemple me permet de juger rapidement si l’outil peut m’aider. --- S’il y a un système de types, je préfère voir les exemples en premier. S’il n’y en a pas : 1) cela me déçoit. 2) je veux d’abord voir des exemples, puis des explications détaillées sur les arguments / retours / structures de données

  • Une bonne documentation a besoin des deux. Il faut d’abord expliquer les détails, puis ajouter des exemples variés pour permettre de vérifier la compréhension. Parfois, des exemples seuls peuvent suffire, mais s’il y a trop de combinaisons d’options, il est presque impossible de toutes les montrer par des exemples. Il faut donc d’abord fournir une explication de chaque option, puis préparer des exemples couvrant autant de cas que possible pour que le lecteur puisse les adapter. Et une bonne documentation est très difficile à produire, et vraiment rare de nos jours

  • Je ne suis pas tout à fait d’accord. La documentation de style Javadoc est une documentation de programmation basée sur les types et les docstrings inline. Elle est indispensable, mais il n’est pas forcément utile d’aller sur le web : regarder directement le code est plus efficace. Les guides avec des exemples ou un QuickStart sont absolument nécessaires. C’est ce qui abaisse la barrière d’entrée d’une bibliothèque. En lisant seulement le code, on ne comprend pas facilement comment utiliser l’API. J’ai eu par le passé l’expérience de nombreuses bibliothèques Java qui ne fournissaient que du Javadoc, ce qui était pénible parce qu’on ne savait pas vraiment comment s’en servir

  • À mon avis, le mieux, ce sont des exemples bien commentés. Mais ils ne peuvent pas remplacer la documentation traditionnelle

  • Je me demande si vous avez envisagé que d’autres personnes puissent avoir un style d’apprentissage différent du vôtre. Je ne comprends pas cette résistance à l’idée que les exemples fassent partie de la documentation. Les exemples réduisent la friction du changement de contexte dans de nombreuses situations

• Les pages man d’Unix ont elles aussi cruellement besoin d’exemples. En général, elles sont rédigées uniquement comme des références pour des gens qui connaissent déjà bien l’outil, donc elles n’aident absolument pas les débutants. Une bonne documentation a besoin des deux

  • Tout à fait d’accord. Je voudrais rappeler à tous les auteurs de pages man qu’il existe une section conventionnelle EXAMPLE. Voir la documentation officielle de man(1)

  • Je n’ai jamais vraiment ressenti ce problème. Je commence par écrire un peu de code, j’apprends au fur et à mesure les commandes et les termes, puis j’examine un à un les codes de retour d’erreur et leurs causes, ainsi que la signification des paramètres. Même sans exemples, une documentation complète suffit. En revanche, ne fournir que des exemples sans aucune explication, c’est vraiment le pire. Quel genre de documentation ne dit même pas ce que sont les paramètres ni ce qu’ils veulent dire ?

  • J’aimais bien le fait que Stack Overflow ait tenté quelque chose de similaire autrefois. Sous le nom de Stack Overflow Documentation, cela a été exploité en bêta de 2016 à 2017. L’objectif était de créer une documentation centrée sur les exemples, mais le projet a été arrêté. Cela dit, le contenu laissé par la communauté reste disponible sous licence CC BY-SA

  • Regardez du côté de cheat.sh. Moi, je l’utilise directement dans mes scripts avec curl cheat.sh/"$1"

  • Je suis toujours surpris de voir à quel point beaucoup de pages man contiennent déjà des exemples. Cela dit, il reste beaucoup de marge pour une amélioration plus globale

• Les exemples ne sont pas utiles qu’aux débutants ou aux utilisateurs occasionnels. Les utilisateurs expérimentés aussi ont besoin d’une documentation de référence, c’est-à-dire d’une documentation qui couvre toutes les configurations de paramètres. Par exemple, la documentation de requests est pénible, car Google m’envoie presque toujours vers une page de type Quickstart remplie d’exemples. Tout le monde sait faire un HTTP GET, mais il est difficile de trouver quelles sont les autres options, comment le timeout est géré, ou si raise_for_status ignore les 204. Il faut les deux, mais si le temps de développement est limité, je choisirais en priorité une documentation de référence correcte. Lien vers le Quickstart de requests

  • Avec des exemples, on comprend beaucoup plus facilement le comportement qu’avec une documentation de type référence. Les gens sont mauvais pour nommer les choses, clarifier les concepts et rédiger de la documentation. Récemment encore, j’ai perdu des heures à cause d’un paramètre qui ne fonctionnait que dans certaines conditions. Le code était trop complexe à analyser, et même un LLM m’a affirmé à tort qu’il s’agissait d’un paramètre non documenté. Au final, la méthode la plus efficace a été de créer du code d’exemple jusqu’à trouver le comportement voulu. Les exemples condensent plusieurs informations importantes et permettent de valider rapidement. À l’inverse, la documentation API essaie de tout couvrir, ce qui la rend difficile à maintenir et l’empêche souvent de transmettre l’essentiel. Et sauf si quelque chose est explicite, je ne fais jamais confiance au comportement d’une bibliothèque. Si ce n’est pas clairement montré dans le README ou défini par les types, je pars du principe que cela peut changer à tout moment. Au bout du compte, j’écris mon code d’appel de la manière la plus défensive possible

  • Les exemples sont importants non seulement pour les débutants, mais pour tout le monde. Un exemple de 5 secondes peut faire gagner l’équivalent d’une heure de lecture de documentation et d’expérimentation. C’est particulièrement vrai pour certaines documentations de git, mais aussi pour des fonctions qui sont fondamentalement simples tout en étant difficiles à expliquer. Même si un développeur ne peut produire qu’une seule chose, il a largement les moyens de fournir à la fois des exemples et de la documentation. Il faut proposer les deux, sauf dans les cas vraiment évidents

  • D’accord. Une bonne documentation doit pratiquement définir clairement l’ensemble du comportement du programme, et il est difficile d’y parvenir avec des exemples seuls

  • On peut avoir les deux en même temps. Exemples et documentation technique ne sont pas incompatibles

  • quand on parle des occasional users, c’est exactement ce dont je parle. À chaque fois qu’on passe d’un projet, d’un langage ou d’un framework à un autre, il y a un coût mental considérable pour retrouver le contexte et comprendre où l’on se situe

• Certains diront ce qu’ils veulent sur Perl, mais sa documentation est vraiment utile. Il y a toujours une section SYNOPSIS au début, avec du code d’exemple immédiatement exploitable. Ensuite viennent les explications, la référence et des exemples supplémentaires. Exemples : documentation de bigrat, documentation de Archive::Tar. Quand on rédige la documentation d’un projet, le style Perl est une bonne source d’inspiration. Et ce style lui-même est bien documenté

  • J’ai utilisé Perl au début des années 2000, puis je m’y suis retrouvé à nouveau par hasard en 2014, et j’ai eu la sensation de me souvenir de tout immédiatement. Je ne sais pas si cela vient de la perspective linguistique et de l’attitude de Larry Wall, mais c’est quelque chose qui marque vraiment. Ce n’est pas de la précision mathématique, mais plutôt une impression de « conversation avec un ami »

• Il faut les deux. Les exemples permettent d’avoir immédiatement une intuition, de faciliter l’intégration, et les explications détaillées sur les paramètres et les réglages aident à résoudre les problèmes complexes et à comprendre l’ensemble. Dès qu’il en manque un, cela devient vraiment pénible. Cela dit, pour une bibliothèque très simple, les exemples peuvent parfois tout expliquer

  • Il faut à la fois des exemples et une documentation de référence. Si possible, ajouter aussi un environnement REPL est une bonne idée. Si l’on peut modifier et tester immédiatement les exemples, cela compense beaucoup de lacunes, même quand la documentation est insuffisante

• Le framework Diátaxis montre très bien qu’il existe différents types de documentation, chacun avec son usage. Il n’y en a pas un qui soit « le meilleur » : l’important est qu’ils répondent à des besoins différents. Site officiel de Diátaxis

  • Ce commentaire devrait être tout en haut. Je trouve frustrant qu’il ait fallu autant de discussion avant que Diátaxis soit mentionné. Les exemples sont au cœur de la documentation, certes, mais je les vois moins comme un « type de documentation » autonome que comme une « technique de documentation » importante

  • Exactement ! Les exemples (ou les tutoriels) constituent un des axes de l’enseignement d’un système. Je ne sais pas avec certitude qui a formulé cela en premier, mais le lien ressemble à celui de l’auteur cité à la fin de l’article : > « Même les grands projets ont rarement les quatre types de documentation à la fois. C’est pourquoi cliquer sur le lien “Documentation” peut parfois faire hésiter » Moi, je préfère la documentation explicative. Quand on comprend la structure ou la raison d’un fonctionnement, on assimile plus facilement les exemples comme les tutoriels. Quand un excellent rédacteur technique ou pédagogue pose bien ce cadre dès le départ, c’est très efficace. En revanche, la référence API est surtout nécessaire lorsqu’on écrit des wrappers ou des implémentations compatibles. À l’origine, beaucoup de projets commençaient avec une référence API privée, et la “documentation” consistait ensuite à ouvrir cela vers l’extérieur. Voir aussi le système de documentation divio

  • Le concept de Diátaxis est excellent. En revanche, il n’est pas facile à intégrer dans un projet réel. Chaque projet a besoin de proportions différentes de documentation, et fournir toutes les formes sur un même site web est inefficace. Cette proportion évolue aussi en permanence avec la croissance de la communauté et le niveau d’expertise. J’aimerais qu’il existe une méthode plus concrète. La documentation est un problème difficile, et j’espère qu’une meilleure solution apparaîtra un jour. Pour l’instant, la qualité dépend du temps et de l’expertise investis, et dans la pratique ces ressources manquent le plus souvent

• Je ressens ce problème très souvent avec Unity et Unreal. Surtout pour Unreal, la documentation des nœuds se contente souvent de répéter le nom du nœud avec une capture d’écran, sans expliquer du tout comment l’utiliser en pratique. Avec Unity aussi, il m’arrive de chercher la documentation pour comprendre la bonne manière d’utiliser une fonction, et de ne rien y trouver. Si je pouvais, j’aurais presque envie de contribuer moi-même des exemples à la documentation Unity

  • La très mauvaise documentation d’Unreal me fait aussi perdre énormément de temps. Chez eux, il y a une mentalité du type « le code fait office de documentation », mais les « explications par capture d’écran de nœud » pour Blueprint sont franchement risibles

  • à propos de £JOB, je me demande si quand les gens écrivent $job, ils l’emploient au sens de travail rémunéré, ou si cela vient simplement du fait que c’est un nom de variable. À ce stade, ma vision du monde vacille

• J’utilise souvent ImageMagick, et je cherchais toujours des exemples sur Google. J’ai donc rassemblé mes notes personnelles dans une petite collection d’exemples de commandes. J’y ai aussi ajouté des explications détaillées sur chaque argument. Comme pour ce billet de blog, je pense qu’il faut des explications en plus des exemples, pas seulement des exemples. C’est encore à l’état de brouillon, mais pour les tâches courantes comme le redimensionnement, l’optimisation ou les calques, c’est déjà très utile. Lien vers mes notes publiques

• Les exemples de code peuvent être exécutés comme des tests unitaires, ce qui évite que la documentation vieillisse ou se casse. C’est un avantage impossible à obtenir avec le langage naturel

  • Maintenant que les LLM progressent, on pourra peut-être aussi tenter, par exemple, de vérifier l’exactitude de la documentation API

• Opinion radicale : si les spécifications d’une méthode donnée ne peuvent pas être déduites intuitivement à partir de sa signature et de quelques exemples représentatifs, alors cette méthode essaie d’en faire trop. Je n’ai pas envie non plus d’apprendre des abstractions encombrantes ou des exceptions complexes

  • Je ne pense pas. Les exemples sont nécessaires non seulement pour cette méthode en elle-même, mais aussi pour montrer « comment l’utiliser avec d’autres méthodes ». Même si l’on pouvait tout déduire de la seule signature, on risquerait encore de manquer des éléments importants comme la configuration préalable, la préparation, ou le traitement du résultat. C’est pourquoi les exemples sont indispensables

[howudoin]

Les exemples sont la meilleure documentation

Dans l’écosystème Java et dans la culture orientée objet, il y a eu particulièrement beaucoup de phrases explicatives dénuées de sens et de documentation formelle, et les frameworks de l’écosystème Python qui ont hérité de cette ambiance sont eux aussi particulièrement pauvres en exemples.

Exemple de documentation dénuée de sens
add(left, right) - additionne l’opérande de gauche et l’opérande de droite

En revanche, ils n’expliquent pas les éléments vraiment importants, comme le type de données des paramètres, les exceptions pouvant être renvoyées, la forme de la valeur de retour ou la structure de fonctionnement.

Avec quelque chose comme les man pages du langage C, même une brève explication suffit pour pouvoir l’utiliser, ne serait-ce qu’en le déduisant à partir du nom de la fonction et des paramètres.