Une distance étrange entre les développeurs et la documentation officielle

Il y a toujours une distance étrange entre les développeurs et la documentation officielle

“Est-ce que je ne comprends pas la documentation parce que je manque de compétences ?” Je l’ai cru pendant longtemps.

1. “Je ne comprends pas, c’est moi”

Frameworks, bibliothèques, REST API, services cloud… Aujourd’hui, la plupart d’entre eux disposent d’une documentation officielle bien faite. Le problème : je ne comprends pas bien.

Au début, je pensais ainsi.

“Ah… c’est parce que je manque encore de compétences. Si je continue à étudier, un jour je pourrai lire cette documentation sans effort…”

Alors je lis assidûment. Mais :

• Le principe reste flou
• Je ne sais pas où commence le concept et où commence l’exemple pratique
• J’ai lu le contenu, mais quand il faut coder, je ne sais pas comment
• Pourquoi la documentation est si volumineuse ?

Je suis maintenant un développeur qui ne se plaint plus de « débutant ». Pourtant, quand je découvre une nouvelle bibliothèque, je me dis encore :

“Wow… c’est encore un nouveau départ…”

Je sais maintenant que ce n’est pas uniquement un manque de compétences.

2. La documentation est écrite du point de vue du créateur

La raison principale de la difficulté est que la plupart des documentations officielles sont rédigées du point de vue du créateur.

• Le créateur connaît déjà
• la structure interne
• les raisons de la conception
• les contraintes
• où et comment chaque fonction est appelée
• La documentation décrit donc souvent
• les paramètres d’une méthode
• le type de retour
• les exceptions levées
• les usages possibles

Le problème : nous ne sommes pas le créateur du programme.

Ce qui nous intéresse, c’est généralement :

• “Où commencer ?”
• “Quel passage de la documentation doit‑je consulter pour résoudre mon problème ?”
• “Dans quel contexte cet option est‑elle utile ?”
• “Quand cette ligne de code est‑elle réellement appelée ?”

Mais la documentation dit :

“Cette option utilise l’action foo et la stratégie bar pour exécuter baz.”

À ce point, on a envie de lancer un exemple avant tout.

3. “Ma documentation est aussi difficile pour les autres”

C’est drôle : je rédige moi‑même la documentation pour mon API ou ma bibliothèque. Je le fais encore du point de vue du créateur.

• “Cette fonction fait ceci…”
• “Cet endpoint accepte ces paramètres…”
• “Il renvoie ce JSON…”
• “En cas de succès/échec, la réponse est…”

Je me dis alors :

“C’est assez clair, non ?”

Mais mes collègues réagissent ainsi :

• “Peux‑tu m’expliquer oralement une fois ?”
• “Il y a une doc, mais je préfère juste demander.”

Plus encore, il arrive que je ne reconnaisse même pas ma propre documentation.

“Euh… c’est bien moi qui l’ai écrite ? Pourquoi l’ai‑je expliquée de façon bizarre ?”

Je réalise alors :

• Écrire une documentation ne garantit pas qu’elle soit compréhensible.
• Je n’ai pas vraiment le droit de critiquer la documentation officielle. 😅

4. Il est normal que la documentation ne soit pas immédiatement compréhensible

Chaque projet a au moins une bibliothèque ou un paquet qu’il utilise constamment. C’est la doc que l’on garde ouverte, toujours prête à être consultée.

Mais il y a un phénomène intéressant.

• Au premier regard : “Qu’est‑ce que ça veut dire ?”
• À la fin du projet : “Ah, je comprends maintenant.”

Je me demande souvent :

“Pourquoi je ne comprenais pas avant ?”

La réponse :

• Comprendre une doc nécessite une expérience pratique et un contexte.
• Pour acquérir cette expérience, il faut au moins essayer de créer quelque chose en lisant la doc.

En d’autres termes, on a besoin d’une compréhension préalable pour comprendre la doc, et on a besoin de la doc pour acquérir cette compréhension : un cercle vicieux.

Je pense maintenant :

“La documentation officielle n’est pas conçue pour être comprise d’un seul coup. C’est seulement après plusieurs projets que l’on commence à la lire correctement.”

Il est donc normal de ne pas la comprendre dès le départ.

5. Les développeurs non‑anglophones ont un +2 de difficulté

Nous avons aussi le handicap d’être non‑anglophones.

• Nous lisons l’anglais sans problème.
• Les termes techniques sont familiers.
• Nous aimons les livres et la lecture, donc nous ne ressentons pas de manque de « compréhension ».

Pourtant, la lecture de la documentation officielle nous fatigue rapidement.

Ce n’est pas un manque de compétences :

• L’anglais lui‑même impose un coût cognitif continu.
• En plus, on reçoit
• de nouveaux concepts
• des API peu familières
• des exemples de code abstraits

En somme, on consomme plus d’énergie que les autres pour comprendre le même contenu.

Quand on se demande pourquoi c’est si difficile, on peut se dire :

“Je suis déjà en train de courir avec un handicap.”

6. Mais nous avons des compétences de survie

Voici quelques stratégies que j’ai apprises pour survivre à la documentation.

6‑1. Abandonner l’idée de lire tout de bout en bout

• La documentation est souvent un manuel de référence + dictionnaire.
• Ce n’est pas un guide d’introduction qui se lit de la première à la dernière page.

Je fais donc :

• Lire rapidement les sections Getting Started / Quickstart / Tutorial.
• Considérer le reste comme
• outil de recherche
• référence en cas de problème

6‑2. Comprendre d’abord par l’exemple, puis lire la théorie

• Écrire une ligne de code.
• Lancer une erreur.
• Rechercher le message d’erreur, puis relire la doc.

Le texte devient alors plus clair :

• Au premier passage : “Je ne comprends pas.”
• Après quelques essais : “Ah, c’est l’erreur que j’ai rencontrée.”

La doc se lit comme une histoire après l’échec.

6‑3. Prendre des notes dans ma langue

La doc est écrite dans leur langue. Je note donc :

• “Si l’option est true, c’est essentiellement le mode XXX.”
• “Cette fonction est comme une usine qui crée X.”
• “Mémorise cette partie, on l’utilisera souvent.”

Quand je reviens plus tard, j’ai ma propre version de la doc, ce qui rend la lecture plus sûre.

7. Ce n’est pas votre faute

Si vous avez lu jusqu’ici, vous avez probablement déjà haleté devant une documentation.

• Des phrases que vous ne comprenez pas après plusieurs lectures.
• Des sections que vous avez lues hier mais que vous devez retrouver aujourd’hui.
• Des passages qui ne deviennent clairs qu’après avoir résolu un problème.

Gardez à l’esprit :

• Vous n’êtes pas seul.
• Même les meilleurs développeurs se perdent.
• Même ceux qui utilisent la bibliothèque quotidiennement consultent souvent Stack Overflow ou GitHub Issues plutôt que la doc officielle.

La documentation est difficile par conception, et ce n’est pas votre faute.

Nous faisons simplement :

• Relire si on ne comprend pas.
• Écrire du code si on ne comprend pas.
• Revenir à la doc après l’échec.
• Répéter jusqu’à ce que l’on comprenne.

C’est une partie de la vie de développeur.

Alors, à ceux qui se sentent découragés aujourd’hui :

“Vous ne faites pas d’erreur. Vous êtes simplement en train de traverser la partie normale du parcours de développeur.”

Nous continuons à coder, à ouvrir des dizaines de tabs, à chercher les pages que nous avons lues hier, et pourtant les projets avancent. 🙂