Une formation technique commence à vieillir le jour où je la publie. Ce n'est pas une formule : c'est la mécanique normale d'un contenu qui décrit des outils en mouvement. Le texte, lui, ne bouge plus.
Je publie une procédure testée sur une version précise. Six mois plus tard, l'option a changé de nom. Un an plus tard, la commande affiche un avertissement de dépréciation. Parfois c'est plus discret : le comportement par défaut change, la commande fonctionne toujours, mais elle ne fait plus exactement ce que la page annonce. C'est le pire cas, parce que rien ne casse visiblement.
Le site compte aujourd'hui plus de 2 400 pages de documentation et une vingtaine de parcours. À cette taille, une personne seule ne peut pas voir immédiatement tout ce qui a bougé. Des audits automatiques tournent, sur les liens morts et sur la fraîcheur des versions, et ils attrapent une vraie partie du problème. Ils ne verront jamais qu'une explication inverse deux concepts, ou qu'il manque une étape entre deux chapitres. Ça, ce sont les lecteurs qui le voient, parce qu'ils sont en train de faire.
Le signalement existait déjà, mais il se perdait
Vous étiez déjà nombreux à me signaler des choses, et c'est précisément ce qui m'a décidé. Le problème n'était pas le silence, c'était la dispersion. Un message sur Discord, un commentaire sous un post LinkedIn, un mail, une réponse dans un fil qui parlait d'autre chose.
Trois défauts venaient avec. Le premier : je perdais l'information. Un bon signalement lu un soir de semaine chargée ne survit pas toujours jusqu'au lendemain. Le deuxième : personne ne pouvait suivre ce qu'il devenait. Vous signaliez quelque chose, et plus rien, sans savoir si c'était noté, refusé ou déjà corrigé. Le troisième : impossible de voir les doublons. Trois personnes pouvaient me remonter le même lien mort sans jamais le savoir.
Un signalement utile doit devenir une action suivie. Tant qu'il reste un message, il dépend de ma mémoire, ce qui est une garantie très faible.
blog-roadmap : le pilotage éditorial, séparé du site
J'ai ouvert un dépôt public dédié, stephrobert/blog-roadmap. La séparation est nette, et elle est volontaire :
| Dépôt | Contenu |
|---|---|
| Le dépôt du site | le code, les guides, les formations, les quiz |
| blog-roadmap | les problèmes, les propositions, les décisions, le suivi |
blog-roadmap ne contient aucune ligne du site. Pas un fichier Markdown, pas un composant, pas une page. Il ne porte que des issues, des discussions et leur suivi. C'est une contrainte que je me suis donnée pour une raison simple : je veux qu'un lecteur puisse signaler un problème sans jamais avoir à regarder du code, et sans se demander si on attend de lui une pull request. On n'attend pas ça de vous.
La conséquence est que la correction se fait toujours dans le dépôt du site, jamais dans celui-là. L'issue décrit le problème, le commit le corrige, et l'issue se ferme en référence à ce commit.
Signaler depuis la page que vous êtes en train de lire
C'est la partie qui change vraiment quelque chose au quotidien. Chaque page de documentation porte maintenant, tout en bas, un bloc qui pose directement la question :
Vous choisissez le type de problème dès le départ, et le bon formulaire s'ouvre. Pas de menu intermédiaire, pas de question sur la catégorie dans laquelle ranger votre remarque : c'est mon travail, pas le vôtre.
Surtout, l'issue arrive déjà remplie. Le titre de la page, son adresse complète, son identifiant interne et sa langue sont transmis automatiquement. Vous n'avez ni à retrouver l'URL, ni à expliquer de quelle formation vous parlez. Il vous reste à décrire ce que vous avez constaté.
Le principe tient en une phrase, et il vaut bien au-delà de ce cas : ne jamais demander au lecteur une information que le site connaît déjà.
Ce qui devient une issue
Une issue représente quelque chose d'actionnable : un résultat attendu est identifiable, et on saura dire le jour où c'est fait. Quatre exemples réels de ce qui la mérite :
- « La commande de la section X ne fonctionne plus avec Kubernetes 1.37 »
- « Le lien vers la documentation officielle renvoie une 404 »
- « Cette explication inverse deux concepts »
- « Il manque une étape entre les chapitres X et Y »
Quatre types se signalent en un clic depuis une page : erreur dans la page, contenu obsolète, lien cassé et amélioration. Deux autres existent sur le dépôt, dont la demande de contenu, pour un sujet, une formation ou un TP qui mériterait d'exister. L'issue vierge est volontairement désactivée : une issue sans adresse de page n'est pas traitable, et c'est exactement ce qui rend un tracker inexploitable au bout de quelques centaines d'entrées.
Et pour les idées ? Les Discussions
Tout ne se range pas dans une tâche. Une idée pas encore mûre, une question sur un passage flou, un retour après avoir suivi un parcours complet : rien de tout cela n'est une action décidée. Forcer ces échanges dans des issues produit un backlog que plus personne n'ose regarder.
La règle que j'applique tient en deux lignes :
- Discussion : un échange, pas encore actionnable.
- Issue : une action décidée, qui doit être faite.
Cinq catégories, pas une de plus, et surtout aucune par technologie :
| Catégorie | Ce qu'on y met |
|---|---|
| Idées et suggestions | une idée avant qu'elle devienne une tâche |
| Formations et pédagogie | enchaînement, niveau, TP, quiz, sujets manquants |
| Questions | une question sur le contenu d'une page |
| Retours d'expérience | « j'ai suivi ce guide avec telle version, et… » |
| Annonces | nouvelles formations, refontes, roadmap |
Une discussion devient une issue dès qu'une action concrète en ressort. « Une formation eBPF aurait-elle un intérêt » est une discussion. « Créer une formation eBPF couvrant bpftrace, Cilium et l'observabilité » est une issue.
Le circuit complet, du clic à la correction
Voici ce qui se passe entre votre signalement et la correction en ligne :
Toute nouvelle issue arrive d'abord dans un Inbox, avant toute qualification. C'est une étape que je tenais à garder : rien n'est jugé à l'arrivée. Une issue y reçoit deux étiquettes posées automatiquement, son origine et le domaine du site concerné, puis j'interviens pour décider de la suite.
Ce qui est public, c'est le backlog : l'issue, son fil, son état, et le commit qui la ferme. Le tableau où je range ces cartes au quotidien reste privé, parce qu'il porte mes arbitrages et mon ordre de passage, pas de l'information utile au lecteur. L'endroit où tout se dit, c'est l'issue.
Pourquoi rendre ce backlog public
J'aurais pu tenir cette liste dans un fichier local. Trois raisons m'ont fait choisir l'inverse.
La transparence. Un lecteur qui tombe sur un problème peut vérifier qu'il est déjà connu, voir ce que j'en ai dit, et suivre sa résolution. Un problème signalé et jamais commenté est une frustration ; un problème signalé, étiqueté et fermé en référence à un commit est une boucle qui se referme.
L'anti-doublon. Avant de signaler quelque chose, on peut chercher dans les issues existantes. Un doublon n'est pas grave, mais un signalement qui complète un fil existant vaut toujours mieux qu'un fil de plus.
La participation, sans barrière technique. C'est le point auquel je tiens le plus. Vous n'avez pas besoin de savoir modifier du Markdown, de forker un dépôt ou de produire une pull request pour améliorer une formation. Un signalement précis est déjà une contribution, et souvent la plus utile : c'est celle que je ne peux pas produire moi-même, parce qu'elle vient de quelqu'un qui découvre le sujet et qui bute là où je ne bute plus.
Ce que j'ai choisi de ne pas automatiser
Le système est volontairement simple. Pas de dizaines de catégories, pas de centaines d'étiquettes, pas de fermeture automatique des idées anciennes, pas de décision éditoriale confiée à un robot.
L'automatisation ne fait que ce qui se déduit mécaniquement : l'origine du signalement, le domaine du site concerné, et le rangement dans le tableau de suivi. Tout le reste est humain, à commencer par la priorité, la décision de traiter et celle de refuser.
Je n'ai installé aucun robot de fermeture pour inactivité, et c'est une décision, pas un oubli. Une idée éditoriale qui dort dix-huit mois reste une bonne idée. Elle attend souvent que le sujet soit mûr, ou que j'aie le temps de le traiter correctement.
La suite : un cockpit de maintenance continue
Aujourd'hui, ce dépôt reçoit des signalements humains : les vôtres et les miens. La direction que je veux prendre est d'y faire converger les autres sources qui détectent déjà l'usure du site, chacune produisant une entrée traitable au même endroit :
- les audits de liens, qui repèrent les cibles externes disparues ;
- les audits de contenu, sur la fraîcheur et la cohérence des pages ;
- la veille de versions, quand un outil publie une release qui invalide une procédure.
Je le présente comme une direction, pas comme une fonctionnalité livrée : aujourd'hui ces audits tournent de leur côté et je les traite à la main. Les brancher sur le même circuit, c'est le travail des prochains mois.
À votre prochaine lecture
Voici ce qui m'aiderait vraiment, et qui prend deux minutes.
Lors de votre prochaine lecture sur le site, si une commande ne fonctionne plus, si une explication vous semble ambiguë, si une étape manque ou si un lien tombe dans le vide : utilisez le bloc en bas de la page. Choisissez le type, décrivez ce que vous avez constaté, et c'est tout. L'adresse de la page part avec, je sais donc exactement de quoi vous parlez.
Et si vous avez suivi un parcours complet, sur Linux, Kubernetes ou Git, venez raconter votre expérience dans les Discussions. Ce que vous avez trouvé trop rapide, l'étape sur laquelle vous avez bloqué, ce qui manquait à la fin : ce signal vaut bien plus qu'un pouce levé, et c'est le seul qui me dise ce qui a manqué à quelqu'un qui est allé au bout.
Un signalement de deux minutes améliore la page pour les milliers de lecteurs qui viendront après vous. C'est, très concrètement, la meilleure façon de rendre service à la personne qui lira ce guide dans six mois.