Il était une fois un petit castor très débrouillard.
Il avait passé des semaines à construire un outil formidable : un système de gestion de troncs ultra-efficace. Interface intuitive (pour lui), logique implacable (selon lui), fonctionnalités puissantes (en théorie). Tout le monde au barrage en parlait déjà.
Alors il décida de le partager. Il créa un dépôt, écrivit fièrement dans le README :
"Installez-le. C’est super simple."
Et il appuya sur "Publier".
Les jours passèrent.
Puis les semaines.
Mais personne ne l’utilisa.
Le hibou grogna qu’il ne comprenait pas comment ça démarrait.
Le renard déclara que la doc disait "lancer le service", mais sans dire quel fichier lancer.
Même le raton-laveur du DevOps jeta un œil… puis se détourna immédiatement.
Le petit castor, désemparé, dit :
— Pourtant, j’ai écrit la documentation !
C’est à ce moment que Père Castor arriva, les moustaches frémissantes, une pile de vieux manuels sur le dos.
Il prit doucement le fichier README.md du petit castor et le lut.
Il cligna des yeux. Puis souffla longuement.
— Ah… mon petit… tu n’as pas écrit une documentation.
Tu as écrit une note à toi-même, avec des incantations techniques en espérant que les autres devinent ce que tu veux dire.
Le petit castor baissa les oreilles.
— Mais… j’ai expliqué comment compiler !
Père Castor hocha la tête.
— Ce n’est pas suffisant. Ce n’est pas une documentation. Une vraie documentation, c’est une forêt balisée, avec des chemins différents selon le voyageur.
Et ça, mon petit, tu ne peux pas l’inventer au dernier moment.
Il s’installa, sortit un vieux parchemin jauni de son sac et dit avec un clin d’œil :
— Laisse-moi te montrer les quatre chemins de la sagesse documentaire.
On appelle cela… le système Diátaxis.
Père Castor déroula son vieux parchemin.
Sur celui-ci, une carte.
Pas une carte au trésor, non… une carte de documentation.
— Voici, mon petit castor, les quatre chemins de la bonne documentation, ceux que tout projet devrait tracer.
Le petit castor pencha la tête.
— Quatre chemins ? Mais moi j’ai tout mis dans un seul fichier...
— Ah ! soupira Père Castor. C’est justement là le problème.
Chaque utilisateur est différent. Certains veulent apprendre. D’autres veulent aller vite. D’autres encore veulent tout comprendre… ou juste résoudre un problème.
C’est pour cela qu’il existe le système Diátaxis. Écoute bien :
« Le premier chemin est celui du tutoriel.
C’est le sentier du débutant, la corde tendue entre deux arbres pour ne pas tomber. »
Le tutoriel prend la patte de l’utilisateur, et pas à pas, lui fait accomplir une tâche complète. Pas forcément utile pour la production, mais rassurante. Il montre que l’outil fonctionne, qu’on peut réussir avec.
— C’est comme quand tu as appris à ta sœur à construire une cabane, dit Père Castor. Tu ne lui as pas lu le plan technique. Tu as posé les rondins, un par un, avec elle.
« Le deuxième chemin est celui du guide.
C’est le sentier botanique, avec ses petits panneaux, pour celui qui veut comprendre les règles de la forêt. »
Le guide explique les principes, les concepts, les choix de conception. Il ne résout pas un problème, il donne une vision d’ensemble. Il construit la carte mentale de l’utilisateur.
— Un bon guide, dit Père Castor, c’est celui qui explique pourquoi l’arbre est tordu, pas seulement comment grimper dessus.
« Le troisième chemin est celui de la référence.
C’est le dictionnaire. Le panneau indicateur. L’encyclopédie. »
Une référence n’a pas pour but d’être lue du début à la fin. On vient y chercher des détails précis : les options d’une commande, les paramètres d’une API, la syntaxe exacte d’un fichier.
— Sans référence, l’utilisateur cherche dans le noir. Avec elle, il va droit au but.
« Enfin, le quatrième chemin est celui du How-To.
C’est la recette. Le guide de dépannage. L’astuce du bricoleur. »
Un How-To répond à une question spécifique : "Comment déployer sur un autre serveur ?", "Comment changer le thème ?". Il est court, ciblé, efficace.
— C’est la réponse qu’on veut à 23h quand tout a planté et que les autres ronflent déjà, glissa Père Castor avec un clin d’œil.
Le petit castor regarda la carte, émerveillé.
— Et si je n’ai que le temps d’écrire un seul type de doc ?
Père Castor sourit tristement.
— Alors tu n’aides qu’un quart de tes utilisateurs. Et encore… si tu écris bien.
Il roula le parchemin, et dit :
« Maintenant que tu connais les chemins, il est temps d’apprendre comment les tracer correctement. »
Le petit castor était motivé. Il connaissait désormais les quatre chemins de la bonne documentation. Il voulait commencer tout de suite. Il attrapa son clavier, ouvrit son éditeur… et commença à taper frénétiquement :
Pour compiler, faire ./configure && make
Le reste est intuitif.
Père Castor toussota bruyamment.
Le petit castor sursauta.
— Tu n’as même pas précisé ce qu’il faut installer avant ! protesta le vieux Castor.
— Mais… moi je sais ce qu’il faut.
— Justement, dit Père Castor. Le but n’est pas d’écrire pour toi, mais pour les autres. Voici quelques conseils et quelques pièges à éviter pour bien écrire sa documentation
Le petit castor tomba sur un tutoriel intitulé :
"Comment intégrer la bibliothèque dans votre app"
Mais le contenu disait :
"Notre bibliothèque permet une interopérabilité fine grâce à une architecture extensible à base de hooks et de loaders. Elle expose un client orienté événements pour faciliter l'intégration."
Pas une commande.
Pas un exemple.
Pas un résultat à atteindre.
Père Castor grogna.
— Ce n’est pas un tutoriel. C’est une pub en prose.
« Ce que tu crois évident ne l’est pas. Ce que tu sais par cœur, d’autres ne l’ont jamais vu. »
Écris pour ton toi du passé, celui qui débutait. Ou mieux : pour ta petite sœur, si elle veut utiliser ton outil.
Pose-toi toujours cette question :
"Si je ne connaissais rien à ce projet… cette phrase me suffirait-elle ?"
Regarde ce texte : "Ce module introduit un paradigme de configuration asynchrone implémentant un pattern de composition extensible…"
Tu comprends ?
Compare à : "Ce module permet de configurer plusieurs actions en parallèle."
Choisis la clarté avant la complexité.
Chaque mise à jour du projet, chaque bug corrigé, chaque retour utilisateur… appelle une nouvelle phrase, une nouvelle section.
Une documentation qui n’est pas à jour est parfois pire qu’une absence de doc.
Un exemple qui ne marche pas est une trahison.
Exécute chaque ligne que tu publies. Copie-colle ce que tu écris dans tes tutoriels. Vérifie que ton lecteur n’ira pas droit dans le mur avec une faute de frappe.
Ton exemple est une promesse. Ne mens pas.
Tu n’as pas besoin de tout faire à la main.
Utilise des outils comme :
La documentation est un projet à part entière. Donne-lui un environnement digne de ce nom.
"Ne fais pas ça" est aussi important que "fais ceci".
Parle des pièges connus, des dépendances à ne pas casser, des comportements étranges mais attendus.
Si tu ne les documentes pas, tu vas devoir les expliquer… encore et encore.
Le petit castor, la tête pleine de conseils, s’arrêta un instant.
— Mais… tout ça, ça prend du temps…
Père Castor sourit.
— Oui. Mais tu sais ce qui prend encore plus de temps ?
Le petit castor hocha la tête.
— Répondre à dix messages par semaine parce que personne n’a compris la doc.
Père Castor referma son carnet.
— Allez, petit. Il est temps de voir comment ton projet va changer… maintenant que les autres vont enfin comprendre ce que tu as construit.
Quelques semaines plus tard, le petit castor publia la nouvelle version de son projet.
Cette fois, il avait pris son temps.
Il avait rédigé un tutoriel simple pour les curieux qui débutaient,
un guide clair pour expliquer comment fonctionnait son système de troncs,
une référence bien rangée pour chaque commande, chaque paramètre,
et plusieurs how-to pratiques pour répondre aux besoins réels.
Et il fit ce qu’aucun castor ne pensait possible…
Il documenta aussi ce qui ne marchait pas bien.
Avant
Après
Puis, il attendit.
Le lendemain, un hibou lui envoya un message :
« J’ai tout installé grâce à ton tutoriel. Trop bien expliqué ! »
Le jour suivant, un raton-laveur fit une pull request pour ajouter un mode “hibernation automatique”.
Puis un renard ouvrit une discussion très calme (ce qui est rare pour un renard) pour suggérer une amélioration.
Et le petit castor vit son projet… grandir.
Non plus comme une cabane qu’il fallait surveiller tout seul…
Mais comme une communauté de castors, hiboux, loutres, humains et autres créatures numériques, qui le comprenaient, l’utilisaient et l’amélioraient.
Père Castor, de loin, observait la scène avec tendresse.
Il tapota son vieux carnet, et murmura :
— Savoir écrire une bonne documentation n’est qu’une facette parmi beaucoup d’autres.
Et ça, mes petits castors… c’est une autre histoire.
Tu travailles sur un projet ?
Pose-toi ces quatre questions simples :
Si la réponse est non… alors il n’est jamais trop tard pour améliorer ta documentation.
Choisis un chemin. Commence petit. Écris pour aider, pas pour briller.
Et tu verras : ta documentation, c’est ce qui transformera ton projet… en héritage.