Comment moi, développeuse débutante, je lis le tutoriel que vous (développeurs) avez écrit pour moi

• Un texte qui décrit avec humour la confusion et les barrières que rencontrent les débutants lorsqu’ils lisent des tutoriels techniques écrits par des développeurs
• Les termes spécialisés et abréviations couramment utilisés par les développeurs sonnent pour les débutants comme une véritable « langue extraterrestre », sans aucun contexte
• Les étapes d’installation, chemins de fichiers et commandes terminal sont souvent trop complexes ou trop elliptiques pour être faciles à comprendre
• L’autrice souligne que des explications évidentes du point de vue d’un développeur deviennent pour un débutant des obstacles exigeant des heures de recherche et de tâtonnements
• Ce texte rappelle aux développeurs qui rédigent des tutoriels qu’ils devraient expliquer les choses avec plus de clarté et de bienveillance du point de vue d’un débutant

---

Contexte du texte et problème soulevé

• L’autrice raconte son expérience de débutante non développeuse lisant des tutoriels écrits par des développeurs
• Elle tourne en dérision le fait de n’avoir absolument aucune idée de ce que signifient les termes techniques et noms d’outils qui apparaissent dans ces tutoriels
• Ex. : en utilisant des noms techniques fictifs comme Hoobijag, Snarfus ou Shamrock portal, elle souligne qu’aux yeux d’un débutant, tout paraît inutilement compliqué

---

Traduction du texte original

« Salut ! Je suis développeuse. Voici mon expérience pertinente : je code avec Hoobijag et parfois j’utilise aussi des jabbernocks, et bien sûr je fais aussi de l’ABCDE++++ (mais jamais de l’ABCDE+/^+, ça serait absurde, non ? haha !) et j’aime travailler avec Shoobababoo, en m’occupant parfois aussi de kleptomitrons. J’ai fini par travailler sur du code lié à Shoobaboo chez Company[1], ce qui m’a menée à Snarfus. Bon, commençons !

À propos de ce tutoriel

J’ai commencé à faire quelque chose de très simple[2] avec Snarfus, et plus je l’utilisais, plus j’en voyais le potentiel ! Le chromus est un peu emmêlé, mais en réalité c’est extrêmement polyvalent. Alors j’ai commencé à argyliser du pintafore avec quagmire au lieu de hoobastank ! Oui, je sais, c’est dingue. Mais ça marchait plus ou moins, et c’était même plutôt amusant… jusqu’à ce que je tombe sur un gros obstacle : fisterfunk ne parlait absolument pas avec shamrock portal, et n’envoyait même pas les beep-boops à Snarfus ! Bien sûr, vous savez ce que ça veut dire[3] — maintenant tout le hoob-tunnel est bouché par des gramelions. Inacceptable.

J’étais à deux doigts d’abandonner, puis j’ai réalisé : si on connecte le backside Snarfus stagnator au backside shamrock Klingon troglodyte emulater, ça marche ! Tout s’est mis à faire beep-boop et ding-dong, et j’ai enfin pu en venir au vrai sujet du tutoriel. Et j’ai pu faire quelque chose de très simple exactement comme je le voulais ! Plutôt cool[4].

Voici donc comment le configurer :

1. Dans le terminal, tapez ajkl;gawgor;iqeg;iJLkqen. wl;R aw;oeiga 4648664 arjarwgj;llj;ja fadgfgajkljl; wlj;sdjk;lfas
2. Allez maintenant dans folder/hidden/deep/in/the/file/system/surprise!.file et copiez le contenu du fichier. S’il n’est pas là, il est peut-être dans library/library/library/llibrary/liiiiiibrarrrary/llllliiiiibrary/hidden/hidden/hiding/you can’t find me/hidden/nope/never/hahahahereiam.file
3. Revenez dans le terminal, collez le contenu du fichier, puis tapez 64A786AGR45JAR; rdja;jg [[]][[]][[]][[]]][()()()()()()()(){{}{}{}|{}{|}{}{|}{ ////////////////!! !!!! !! //// !!! agjlkargji;lwej;OI [ASRGASG[]ASGDASG[]EAEadgasg[]EAGE[edaga][]ahgr-0-0=-0-=0-=0=0-0=-0-=0=-0-=0=-0=-0!!!
4. Boop![5]
5. Ouvrez Snarfus et téléversez le fichier que vous venez de créer
6. Juste pour le fun, si vous voulez aussi désactiver le sham du chronostatiomatrix —()()(]]asdg a=-do —cd go cd stay —sususudododo baby shark—][] peut être exécuté. C’est optionnel
7. C’est fini !

Dites-moi comment ça se passe. Je me demande aussi si quelqu’un utilise cette méthode avec GewGawGamma ou ometer2.7. »

---

Explication des notes

1. Ça a l’air d’être une entreprise connue, mais moi je ne la connais pas
2. Ce n’est absolument pas simple
3. Je n’ai aucune idée de ce que ça veut dire
4. C’est cool, mais je n’ai toujours rien compris. Cela dit, tant mieux si vous, vous y arrivez
5. Les trois premières étapes demanderont probablement environ 7 heures et 193 recherches. Mais une fois arrivé à Boop!, c’est extrêmement grisant

Conclusion

• « Ce texte a été écrit juste pour le plaisir. Merci sincèrement à toutes celles et tous ceux qui partagent leurs connaissances et prennent le temps de rédiger des tutoriels. »

[GN⁺]

Commentaire Hacker News

• Je recommande vivement de faire suivre la documentation à quelqu’un qui n’a qu’un minimum de connaissances, puis de rester à côté en observant sans rien dire. Il ne faut pas aider du tout, seulement observer. Cela permet d’identifier toutes sortes de problèmes : les endroits où l’utilisateur bloque, les points que l’auteur connaît tellement bien qu’il n’y pense plus, ou encore des réglages omis. Si l’utilisateur atteint l’objectif sans stress particulier, la documentation est validée. Sinon, il faut noter sans rien oublier chaque point de blocage, améliorer chacun d’eux, puis refaire le test avec une autre personne. J’ai vu des documentations de grandes entreprises comme celles des FAANG qui ne passeraient pas ce critère. Je suis vraiment reconnaissant que notre organisation ait fixé un niveau d’exigence élevé. Rédiger la documentation de cette façon réduit les réunions répétitives, les demandes de support et les appels vidéo, et permet aux utilisateurs de résoudre eux-mêmes leurs problèmes

  • J’ai souvent rencontré ce problème avec la documentation d’Apple. Les définitions s’y contentent souvent de répéter le nom d’un concept sans vraie explication, alors qu’il faudrait être plus concret
  • La règle « ne rien dire, seulement observer » semble simple, mais en pratique beaucoup de gens n’arrivent pas à se retenir : ils finissent par expliquer ou donner des indices. Certains vont même jusqu’à prendre la souris eux-mêmes. Pour éviter cette réaction très humaine, il peut être utile d’avoir un modérateur neutre séparé, tandis que l’auteur ou le développeur se contente d’observer. Mais il reste important d’apprendre l’art de « simplement regarder », et si vous voulez aller plus loin, je recommande de vous renseigner sur le « think-aloud protocol »
  • La plupart des documents d’onboarding des équipes en entreprise sont d’une qualité désastreuse, et c’est souvent une vitrine fidèle de la charge réelle du travail. Les trois équipes que j’ai rejointes récemment avaient soit très peu de documentation, soit une documentation obsolète ; j’ai dû aller voir directement les personnes concernées pour obtenir les accès nécessaires ou des informations sur le pipeline de déploiement. Dans le processus, on rédige de nouveaux documents, mais dès qu’un système ou une permission change, ils deviennent à nouveau périmés : un cercle vicieux. Une seule équipe m’a configuré tout l’environnement nécessaire en deux jours, et l’expérience était excellente. Je travaille maintenant dans une nouvelle équipe devex pour améliorer l’environnement documentaire lui-même
  • Faire son onboarding avec une mauvaise documentation d’installation donne vraiment l’impression d’ajouter un facteur 10 au stress. J’ai toujours encouragé les nouvelles recrues à corriger immédiatement, comme première contribution, les problèmes qu’elles ont elles-mêmes rencontrés. Comme elles n’ont aucun contexte, elles font d’excellents relecteurs
  • Notre organisation utilise le même workflow. Nous demandons à des personnes peu expérimentées de suivre la documentation, puis nous encourageons tout le monde à l’améliorer en continu. Les nouveaux repèrent bien les « angles morts » qui apparaissent avec l’expérience. D’après mon expérience, j’ai aussi appris qu’il est très important de gérer la confiance de l’utilisateur. C’est pourquoi, pour des étapes du type « exécutez cette commande shell », nous fournissons par défaut plusieurs sections repliables : par exemple un exemple de sortie réussie, les avertissements que l’on peut ignorer, la liste des erreurs possibles avec leur traitement, ou l’explication de commandes complexes. Certaines étapes ont même une page entière d’explication, mais pendant l’onboarding ce niveau de détail aide énormément

• Le titre du billet de blog était « Moi, non-développeur, lis le tutoriel que vous, développeur, avez écrit », mais le titre sur HN a été changé en « Moi, développeur débutant... ». Un non-développeur et un développeur débutant, ce n’est pas du tout la même chose. Par exemple, pour les RH ou quelqu’un totalement hors du domaine, même le vocabulaire interne ou les concepts de base peuvent être entièrement inconnus. Dans ce cas, si un développeur écrit des explications complètement déconnectées, il mérite d’être critiqué. En revanche, un développeur débutant, même s’il trouve cela difficile, peut chercher lui-même les nouveaux termes ou concepts, puis plus tard mettre à jour la documentation pour les prochains débutants

  • Pour information, le billet a bien été soumis avec le titre « non-développeur », puis a été changé en cours de route en « développeur débutant ». L’autrice est une blogueuse non spécialiste du technique, et pour gérer un site web ou du CSS, elle a forcément dû consulter plusieurs documentations techniques. Je pense qu’il aurait aussi été pertinent de discuter de la publication de sites et de l’absence de documentation pour les non-spécialistes, mais le fait que la communauté HN ait emmené la discussion dans une autre direction me paraît aussi acceptable
  • Cette distinction est très importante. L’autrice, Annie, dit elle-même qu’elle travaille dans le « contenu / la documentation » et qu’elle a aussi un hobby autour du CSS, donc elle relève plutôt de la catégorie des « développeurs amateurs non professionnels ». Je pense que c’est un segment appelé à grandir. Quand on écrit des tutoriels destinés aux débutants ou aux non-développeurs, il suffit parfois d’ajouter une toute petite précision à une phrase comme « cd ~/.snarfus (créez le dossier s’il n’existe pas) ». Moi aussi, à l’époque où j’installais Debian, ce genre de minuscule explication m’a énormément aidé
  • Le site qui m’avait marqué quand j’ai commencé à programmer, c’était « FromZero ». Il expliquait pas à pas, pour des non-développeurs, depuis l’installation de l’IDE jusqu’à l’ouverture de la console. Et quand un terme inconnu apparaissait, il rassurait le lecteur avec des phrases du type « nous verrons cela plus tard, ne vous en préoccupez pas pour le moment », ce qui était excellent. Bien sûr, rédiger de la documentation demande beaucoup de temps et d’efforts, donc parfois une explication partielle vaut mieux que pas d’explication du tout. Je pense qu’une documentation pour développeurs débutants devrait être rédigée avec le même niveau d’attention qu’une documentation pour non-développeurs
  • Certaines personnes considèrent que si on ne leur explique pas absolument tout de manière extrêmement simple, c’est du gatekeeping ; elles oublient qu’on ne peut pas tout comprendre instantanément sans connaissances préalables, même si l’on a l’impression que c’est difficile
  • Si c’est un tutoriel destiné à des développeurs débutants et non un texte écrit pour des développeurs professionnels, il est étrange d’exiger qu’il explique dans le détail chaque concept du type « Hoobijag » ou « shamrock portal ». En réalité, nous avons tous commencé par chercher ces termes sur Google

• La plupart des tutoriels ne sont pas vraiment destinés aux non-développeurs, mais ressemblent plutôt à un échange d’informations entre développeurs pairs, un peu comme des articles académiques destinés à un groupe disposant déjà d’un certain bagage. Et cette approche n’est pas mauvaise en soi. Elle me permet même de retrouver facilement des notes que j’avais prises autrefois. C’est aussi pour cela qu’il existe des cours et des manuels destinés aux débutants. Si un tutoriel devait à chaque fois commencer par 30 000 caractères de contexte général, personne n’irait au bout. À l’inverse, même avec davantage de contexte, quelqu’un pourra toujours trouver que ce n’est pas encore suffisant

  • Mon fils de 17 ans s’intéresse beaucoup à la programmation ; récemment je lui ai expliqué les notions de public/private/internal/static ainsi que la récursivité. J’attends maintenant de voir quelle sera sa réaction la prochaine fois
  • Je ne suis pas d’accord avec l’idée que « les tutoriels ne sont généralement pas destinés aux non-développeurs ». Je tiens à souligner que le titre même de ce tutoriel visait explicitement les non-développeurs. Quand on galère à installer un projet open source, on a vraiment besoin de voix pour dire que même un guide d’installation très basique devrait être assez simple pour qu’un débutant puisse le suivre. Omettre une étape minime peut faire perdre des heures entières dès qu’on sort d’un domaine familier
  • Je ne pense pas qu’écrire une documentation plus accessible pour tout le monde soit une mauvaise chose. Une bonne documentation est utile non seulement aux débutants, mais aussi aux développeurs. Si une documentation accessible n’existe pas, c’est souvent simplement parce que l’on ne veut pas fournir un petit effort supplémentaire. De plus, contrairement à un article scientifique, la documentation des développeurs est souvent trop sommaire, ou rédigée sans réelle attention pour le lecteur. Au final, cela donne des documents inutiles à quiconque n’est pas déjà expert. C’est un échec
  • Je suis d’accord sur la nécessité d’une documentation qui construise le contexte pas à pas pour les débutants. En revanche, ces derniers temps, on cherche parfois à améliorer la DX uniquement sous l’angle du « facile », au prix de fonctionnalités autrefois utiles comme les logs détaillés ou la possibilité de chercher efficacement dans les messages d’erreur ; au final, on vise seulement les débutants et on rend l’outil plus pénible pour les utilisateurs existants
  • Aujourd’hui, beaucoup de tutoriels ressemblent surtout à des billets servant à gérer son historique du type « j’ai contribué au projet X ». L’auteur ferait peut-être mieux de reprendre son propre tutoriel trois mois plus tard : les éléments manquants sauteraient alors immédiatement aux yeux, et cela améliorerait énormément le résultat

• Beaucoup de technical writers n’ont pas vraiment conscience de la « malédiction du savoir ». J’ai autrefois dirigé une guilde sur WoW (World of Warcraft). Quarante personnes entraient ensemble dans un donjon et devaient coopérer contre plusieurs boss, où la moindre petite erreur pouvait provoquer un wipe général. Nous nous retrouvions donc tous sur Teamspeak pour expliquer la stratégie en détail à l’avance. La plus grande leçon que j’en ai tirée, c’est : « pars du principe que l’autre ne sait pas de quoi tu parles » et « répète même ce que tu as déjà dit une fois ». La plupart des gens n’interrompent pas pour poser des questions quand ils ne savent pas, donc prendre l’habitude de se demander en permanence « quel terme suis-je en train d’utiliser ? » ou « cette personne ne connaît peut-être pas ce concept » et d’ajouter une explication a eu un effet énorme. Cette expérience de communication s’applique telle quelle à la communication technique, et si l’on s’entraîne à dépasser la « malédiction du savoir », on améliore vraiment la compréhension des autres

  • Dans mon ancienne guilde de raid, voir un chef de guilde de 18 ans rassembler des adultes sur plusieurs fuseaux horaires et gérer sans heurts la répartition, la stratégie et le calendrier m’avait fait penser : « ce type devrait être embauché tout de suite comme manager »
  • Quiconque a déjà géré un raid à 40 possède forcément des compétences de tout premier ordre en gestion de projet. C’est littéralement comme mener sans bavure un troupeau de chats égarés

• Beaucoup de pages d’accueil de projets ou de README GitHub sont rédigés comme si « la personne qui lit sait déjà tout ». Quand je consulte une documentation, j’aimerais qu’elle apporte davantage d’attention à des points comme : pourquoi cet outil est nécessaire, quel problème il résout, en quoi il diffère d’autres outils similaires, s’il est encore réellement utilisé aujourd’hui, et si elle donne assez d’éléments pour permettre au lecteur de juger lui-même des avantages et des inconvénients. Il suffit parfois de consacrer cinq minutes à se demander « même un grand débutant, qu’est-ce qu’il voudra savoir ? » et de l’écrire pour rendre la documentation bien plus accessible. Même quand un projet a demandé des années de travail, il est vraiment dommage que les utilisateurs abandonnent sans même que l’auteur s’en rende compte, juste parce que cela leur a paru trop pénible. Et il est aussi important de bien comprendre le rôle de chaque type de documentation. https://diataxis.fr/ est un très bon point de départ

  • Dans le domaine ROS (logiciel robotique), j’ai toujours trouvé les README atrocement insuffisants, au point d’en être constamment stressé. Souvent, en dehors du nom du projet, il n’y a aucun indice, si bien qu’il est difficile de comprendre à quoi il sert. Ce n’est pas un problème propre à l’open source : j’ai vécu exactement la même chose au travail, et j’ai parfois l’impression d’être le seul à ajouter des explications dans les README. J’étais presque plus heureux à l’époque des monorepos
  • Je comprends bien que ce sont des outils créés avec passion et beaucoup de travail par des développeurs, mais rien qu’en prenant soin de la documentation, la barrière à l’entrée baisserait énormément. Et si, en plus, la documentation des autres composants de la stack est elle aussi difficile, la courbe d’apprentissage devient exponentiellement plus raide
  • Sur HN, il y a même déjà eu des projets publiés sans indiquer ce qu’ils étaient exactement

• Le plus important, quand on rédige une documentation, est de définir clairement le niveau de connaissance du lectorat visé. Peu importe qu’on place la ligne de base haut ou bas ; si l’on s’en écarte trop, une partie des lecteurs sera forcément mécontente. Dans ce genre de situation, on peut choisir l’excuse ou chercher une solution. En réalité, aujourd’hui, avec l’IA, Google, les livres, etc., on peut trouver immédiatement presque n’importe quoi. Si l’on se demande ce qu’est « Shoobababoo » ou pourquoi on utilise « quagmire », il suffit de chercher. Bien sûr, dans l’idéal, une documentation devrait être aussi autonome que possible et dépendre le moins possible d’informations externes, mais le monde ne fournit pas toujours ce niveau de bienveillance

  • C’est précisément pour cela que la tendance des guides d’installation qui commencent par « maintenant double-cliquez sur le fichier exe puis cliquez sur suivant » est encore plus problématique. Définir la bonne ligne de base est vraiment essentiel
  • J’écris surtout de la documentation pour des systèmes internes sensibles, et il m’arrive d’indiquer clairement au tout début : « ce guide suppose que vous savez déjà utiliser x, y et z. Sinon, vous ne devez pas effectuer cette opération ». L’accès est déjà restreint, mais comme quelqu’un de peu familier pourrait quand même s’en servir dans un scénario de DR, par exemple, je préfère parfois laisser volontairement une frontière du type « si vous ne comprenez même pas cela, ne le faites surtout pas »

• Le principe que j’ai longtemps mis en avant dans le mentorat, c’est : « le mieux, c’est de partager ce que l’on sait ». Si vous savez quelque chose, expliquez-le. Si la personne le savait déjà, vous lui aurez simplement apporté de la confirmation ; si elle ne le savait pas, cela lui aura été très utile. Il y a parfois des plaintes disant que c’est trop verbeux, mais quand je réponds « c’était au cas où un junior, un client ou un manager tomberait dessus », la plupart des gens comprennent. Ce principe vaut dans tous les domaines : développement, reporting, gestion des personnes, etc.

  • Bien sûr, certaines personnes détestent au plus haut point qu’on leur explique quelque chose qu’elles savent déjà. Si le ratio signal/bruit devient trop mauvais, cela peut au contraire nuire à la communication elle-même
  • J’ai vécu quelque chose de similaire en apprenant le billard à mon fils. Une culture d’équipe où l’on baisse sa garde et où l’on partage sans retenue ses conseils aide énormément à progresser. En mentorat, si l’on guide quelqu’un par des questions plutôt que de lui donner directement la réponse, le vrai progrès se produit quand il arrive lui-même à la trouver
  • Expliquer systématiquement les choses à tout le monde peut aussi être perçu comme du « mansplaining » ou comme une posture politique de « je fais comme si je savais tout ». En entreprise, il est parfois plus prudent de se contenter de répondre quand les autres posent des questions

• Récemment, en essayant de déployer une application depuis Gitlab vers DigitalOcean Kubernetes, j’ai dû mettre en œuvre trois ou quatre outils tiers sans aucune explication sur leur rôle, et il fallait aussi deviner soi-même quels noms ou chemins saisir en ligne de commande. Aucune explication sur ce qui servait de référence ni sur ce qu’il fallait faire correspondre. Pourtant, j’ai un assez bon niveau sur Docker, mais la documentation de ces outils était à ce point peu accueillante qu’elle aurait presque mieux fait de ne pas exister

• La raison principale pour laquelle j’ai arrêté d’écrire des livres pour créer un site de tutoriels, c’est que les tutoriels peuvent devenir bien plus accessibles grâce à divers outils interactifs (<abbr> et autres). Malgré cela, je trouve frustrant que le contenu web d’aujourd’hui reste encore au niveau fonctionnel du livre papier. On dispose pourtant de clics, de survol, de sections repliables, de vidéo, de retour utilisateur et d’innombrables possibilités, mais on voit toujours surtout d’interminables murs de texte. Même l’OP, par exemple, utilise des notes de bas de page qui font défiler jusqu’en bas de page quand on clique dessus ; cela donne l’impression de ne pas exploiter pleinement le potentiel du web

  • Je suis justement en train d’essayer de moderniser mon blog ; si vous pouvez recommander des sites qui font bien ce genre de tutoriels interactifs, j’en serais reconnaissant

• En réalité, la plupart des tutoriels ne sont adaptés ni aux non-développeurs ni aux développeurs : ce sont surtout de longs textes inutiles qui finissent quand même par omettre une ou deux étapes cruciales. À mon avis, la cause principale est que rédiger comme si l’on expliquait quelque chose à quelqu’un d’autre est difficile. Si l’on n’explicite pas par écrit ce que l’on ne connaissait jusque-là que dans sa propre tête, le lecteur ne pourra jamais le deviner. Au lieu d’écrire un « tutoriel », il vaudrait mieux adopter une forme de « cookbook », plus pratique à l’usage réel et moins susceptible de devenir inutile après une montée de version

  • Ironiquement, de nos jours, les recettes de cuisine en ligne ont souvent encore plus de bavardage inutile que les blogs de non-développeurs