Que fait explain-it ?
Transformez le code que vous avez investigué en un petit site HTML statique qu'un lecteur intelligent sans aucun contexte sur ce codebase peut suivre : une page racine qui construit le modèle mental, une page par sujet, et une barre latérale qui les relie.
Le niveau à atteindre : "un langage simple qui n'est ni trop simpliste ni trop difficile". Ne jamais prendre de haut ; ne jamais supposer la connaissance du dépôt.
Workflow
1. Enquêter avant d'expliquer
N'expliquez jamais du code que vous n'avez pas lu. Pour chaque sujet, lisez la source réelle : les lignes modifiées, la fonction englobante, et au moins un appelant, afin de pouvoir répondre à la question "quand ce code s'exécute-t-il ?" avec une histoire vraie. Si une affirmation provient de quelqu'un d'autre (un commentaire de revue, un problème), vérifiez-la d'abord dans le code et dites-le si elle ne tient pas.
2. Planifier le site
- Une page racine (
index.html) : le primer. Il construit le modèle mental du système pour le lecteur en ~2 minutes et renvoie à chaque page de sujet. - Une page par sujet (
01-<slug>.html,02-<slug>.html, …) : chaque page explique un changement, un bug, une décision ou un sous-système. 3 à 7 pages est la zone idéale ; fusionnez les sujets plutôt que de dépasser ~9. - Une barre latérale partagée sur chaque page listant toutes les pages dans l'ordre de lecture, avec la page courante mise en évidence. Les pages sont des fichiers plats liés avec des
<a href>relatifs — le site doit fonctionner en l'ouvrant directement depuis le disque (file://), donc pas de routeurs, pas d'étape de compilation, pas de JS externe.
Demandez à l'utilisateur où placer le dossier seulement si aucun emplacement n'est évident ; sinon créez un dossier nommé de manière sensée à côté du travail (par ex. docs/explainers/<topic>/) et dites où vous l'avez mis.
3. Rédiger chaque page
Suivez references/writing-guide.md pour la méthode — lisez-le avant d'écrire votre première page. Les incontournables :
- Primer d'abord. La page racine présente tous les concepts du domaine dont les pages de sujet ont besoin, chacun avec une métaphore concrète (par ex. "une release est une photocopie ; un job en cours épingle une photocopie"). Introduisez une métaphore une fois, puis réutilisez-la textuellement partout. N'empilez jamais deux métaphores pour un seul concept.
- Ancrez chaque sujet dans l'exécution. Chaque page de sujet s'ouvre sur une histoire "Quand ce code s'exécute-t-il ?" : 2 à 4 séquences acteur (L'utilisateur fait X → Le système exécute la fonction Y → la petite tâche à l'intérieur). Les vrais noms de fonction en police de code, en complément — jamais à la place — de l'histoire en langage simple.
- Montrez le changement sous forme de diff. Code ancien vs nouveau dans des blocs diff rouge/vert avec le chemin du fichier dans l'en-tête, réduits à l'essentiel, avec 1 à 3 commentaires en ligne pointant vers pourquoi — pas racontant quoi.
- Quantifiez le "pourquoi". "Lent" est interdit ; "des centaines de Ko par requête, ~99% du temps pour rien" est la norme. Même chose pour le risque : nommez l'entrée/l'état concret et le résultat erroné.
- Séparez les bugs des décisions. Si quelque chose est un choix produit défendable plutôt qu'un défaut, présentez-le comme une décision avec le compromis, pas comme une erreur.
- Terminez la page racine par un tableau de bord : un tableau d'état de chaque élément (fait / proposé / en attente) avec son emplacement dans le codebase.
4. Construire le HTML
Copiez references/site-template.html comme point de départ pour chaque page — il contient les tokens de design, la barre latérale et un exemple fonctionnel de chaque composant (bloc d'histoire, encadré, bloc diff, tableau d'état, pastilles). Ensuite :
- Gardez chaque page entièrement autonome (tout le CSS en ligne dans la page). La barre latérale est dupliquée dans chaque page avec l'élément courant marqué
class="on". - Suivez
references/design-system.mdpour les tokens et les règles des composants. Gardez la palette, l'espacement et l'échelle typographique tels que donnés pour que les sites multi-pages ressemblent à un seul système. Le modèle fournit un bouton clair/sombre et une barre latérale repliable — conservez les deux dans chaque page plutôt que de les supprimer. - Aucune dépendance externe, sauf le lien Google Fonts déjà présent dans le modèle (la pile de polices retombe proprement hors ligne) et aucun JS au-delà du snippet de basculement de thème du modèle.
5. Vérifier avant de remettre
Ouvrez ou affichez la page racine et au moins une page de sujet (ou relisez-les) et vérifiez : chaque lien de la barre latérale résout, chaque identifiant de code mentionné dans le texte existe dans le codebase avec cette orthographe exacte, chaque diff compile conceptuellement par rapport au fichier réel, et les statuts du tableau de bord sont à jour. Ensuite, indiquez à l'utilisateur le chemin du dossier et ouvrez la page racine pour lui si l'environnement le permet.
Pièges courants
- Expliquer de mémoire de la conversation plutôt que du code — l'expliqueur hérite de toute affirmation périmée. Relisez la source.
- Dérive de métaphore : appeler "photocopie" sur une page et "copie gelée" sur la suivante. Un seul terme, partout.
- Blocs diff qui collent 60 lignes textuellement. Réduisez à l'essentiel ; gardez 2 à 4 lignes de contexte autour.
- Texte qui décrit le diff ligne par ligne. Le diff montre quoi ; le texte ne porte que pourquoi c'est important et quand ça s'exécute.
- Barre latérale qui n'existe que sur la page d'index. Chaque page porte la barre latérale complète.
- Langage bébé ("l'ordinateur se souvient des choses dans une boîte spéciale"). Le lecteur est intelligent — il ne connaît simplement pas ce codebase.