Animation de mécanismes (mechanism-animation)
Transformez « comment ça marche » en une animation pas à pas d’une page : le lecteur fait défiler une étape à la fois, chaque étape ne traite qu’une chose, et les éléments de l’image apparaissent, se déplacent et disparaissent dans un ordre causal.
Référence du résultat final : assets/template.html, un modèle avec un petit exemple en 4 étapes (pas de cache → ajout d’un cache), ouvrable directement dans un navigateur.
0. Décider s’il faut faire une animation
Essayez du moins cher au plus cher ; si l’étape précédente est suffisamment claire, ne passez pas à la suivante :
| Niveau | Utilisation | Quand est-ce suffisant |
|---|---|---|
| 1 | Écrire directement | Deux ou trois phrases suffisent à expliquer |
| 2 | Étapes numérotées (1., 2., 3.) | C’est un processus, mais chaque étape tient en une phrase, le lecteur n’a pas besoin de « voir » |
| 3 | Étapes numérotées + 2 à 3 images statiques (avant/après) | Structure, relations ; ou un processus décomposable en deux ou trois images fixes compréhensibles |
| 4 | Cette compétence : animation pas à pas | Il s’agit de savoir où les choses vont, leur ordre, qui partage les mêmes données, ce qui a été supprimé à quelle étape, et trois images fixes ne suffisent pas à expliquer |
Critère en une phrase : Si l’image figée à n’importe quelle étape est encore compréhensible ⇒ une image statique suffit ; s’il faut voir le mouvement pour comprendre ⇒ faites une animation.
Deux limites :
- Coût. L’animation coûte plusieurs fois plus cher qu’une image statique (vérification des faits, ordonnancement, réglage du temps, tests, allers-retours). Quand personne ne demande explicitement une animation, proposez d’abord, expliquez pourquoi les trois premiers niveaux ne suffisent pas, et ne commencez qu’avec l’accord de l’autre partie ; ne partez pas du principe qu’il faut en faire une.
- L’animation ne sert qu’à « comprendre pour la première fois », pas comme matériel de référence : on ne peut pas la parcourir, la chercher, ni l’insérer dans un document. Donc la page doit se terminer par un « aperçu complet du processus » (le modèle génère automatiquement une ligne par étape) ; conservez la version texte originale du document et ajoutez un lien vers la page d’animation, ne remplacez pas le document par l’animation.
1. Processus
- Vérification des faits. L’animation rend les erreurs très vivantes. Avant de dessiner, vérifiez le mécanisme à expliquer avec le code / le document de conception / l’article scientifique, et distinguez « ce que dit la conception », « ce que fait le code actuellement » et « ce que font les autres (articles, valeurs par défaut) ». En cas de doute, écrivez « déduction, à vérifier expérimentalement ».
- Écrivez le storyboard (pas de code). Suivez
references/storyboard.mdpour créer un tableau : une ligne par étape, indiquez clairement quelle chose est expliquée à cette étape, ce qui apparaît / bouge séquentiellement à l’écran, ce qui reste à la fin, et la phrase à gauche. Ne commencez à coder qu’après avoir validé le storyboard selon les règles de la section 2. Si le nombre d’étapes est élevé (> 6) ou si la narration n’est pas claire, discutez d’abord avec la personne qui a fait la demande : envoyez uniquement le tableau et une question sur laquelle elle doit trancher, pas un document complet ; si la personne préfère voir directement le résultat final, passez directement à la réalisation. - Partez du modèle :
cp assets/template.html <répertoire de sortie>/<nom>.html. Modifiez uniquement trois endroits :- Dans le HTML :
<title>, page d’accueil (#top),aria-labelde l’image, page de fin (#where, avec le pied de page « Mis à jour : mois/année · Vérifié sur quelle version ») — ces parties du modèle contiennent encore l’exemple, remplacez-les une par une ; - Bloc A du script :
PAGE,MODULES(modules, étapes, texte, durée par étape) ; - Bloc C du script : scène (objets, mouvements à chaque étape).
Les blocs B1 / B2 sont le moteur, généralement ne les touchez pas. Pour la syntaxe, les utilitaires et les astuces existantes, voir
references/engine.md.
- Dans le HTML :
- Auto-test :
node scripts/check.js <page.html> <répertoire de captures>. Les 10 éléments ne doivent pas être FAIL (sicontainn’a pas de marqueur de cible dans la page, c’est SKIP, c’est normal), puis examinez chaque capture une par une :step-NN(fin de chaque étape),mid-NN(milieu de chaque étape),page-NN(page entière). Le script ne vérifie que « arrêté ou non, texte compressé ou non, hors cadre ou non, taille de police suffisante », pas « explication claire ou non ». Une page de 4 étapes prend environ 1 minute, 12 étapes environ 3 minutes ; pour l’installation des dépendances et l’utilisation, voir la fin de engine.md. 4.5 (Si le nombre d’étapes est élevé ou si l’explication s’adresse à des non-initiés) Test avec une « première fois » : créez un sous-agent qui ne connaît pas ce mécanisme et n’a lu aucun document, donnez-lui uniquement les captures de chaque étape de la page, dans l’ordre, puis demandez-lui de répéter de mémoire ce que chaque étape explique, si c’est l’image ou le texte qui le lui a appris, et ce qu’il n’a pas compris. Ce qu’il ne comprend pas est un problème de la page, pas de lui — c’est plus efficace que de se relire dix fois. - Livraison : fournissez la page (un seul fichier HTML, sans dépendances externes) à la personne qui a fait la demande. Après chaque modification, relancez l’auto-test avant de livrer.
- (Si le contenu est important) Vérification technique : une fois la page finalisée, lancez une vérification en lecture seule, en confrontant chaque phrase et chaque nombre de la page au code et à la documentation phrase par phrase, et produisez une liste « erreurs / trompeur / imprécisions » ; la personne qui a fait la demande décide ce qui doit être corrigé. La vérification ne porte que sur les faits ; la qualité de l’explication est laissée à l’appréciation de la personne qui a fait la demande.
2. Règles de narration (les plus importantes, toutes apprises à la suite de retours)
Ordre
- Du plus facile au plus difficile, d’abord le « cas normal » puis le « cas problématique ». Le lecteur doit d’abord voir à quoi ressemble la situation normale pour comprendre où se situe le problème. Exemple : expliquez d’abord que plusieurs conteneurs partagent la mémoire d’une même VM (pas de problème), puis expliquez qu’avec plusieurs VM, chacune stocke sa propre copie (problème), puis la solution.
- D’abord le niveau inférieur, puis le niveau supérieur, couche par couche. D’abord seulement l’hôte → les données entrent dans la mémoire de l’hôte depuis le disque → la VM apparaît → les données entrent dans la VM → enfin seulement, le programme à l’intérieur. Ne placez pas toutes les boîtes dès le début, et ne faites pas apparaître le programme avant les données.
- Si plusieurs événements dans une étape ont un lien de causalité, ordonnez-les ; ne les faites pas se produire en même temps. Après « le conteneur s’arrête », « sa mémoire se libère », puis « elle est rendue à l’hôte ».
- L’image n’apparaît qu’une fois le défilement arrêté, l’animation de la première étape se joue depuis le début ; le modèle gère cela, ne le cassez pas.
Ce que chaque étape doit expliquer
- Une étape ne traite qu’une seule chose, le titre est cette chose („Chaque page lit une fois“), pas un nom („Phase de lecture“).
- La ligne principale ne montre que la pratique réelle. Les valeurs par défaut, les pratiques des autres, les solutions historiques sont mentionnées dans les points clés de cette étape avec une phrase expliquant „pourquoi faire cela spécifiquement“ ; ne les transformez pas en une étape séparée — sinon le lecteur pensera qu’il faut d’abord suivre cette étape-là. (Contre-exemple : d’abord montrer „rapporter par blocs de 2 Mo“ puis „rapporter par blocs de 4 Ko“ → le lecteur demande : „D’où vient ce 2 Mo ? Lequel doit-on faire en premier ?“)
- Deux étapes qui se ressemblent seront perçues par le lecteur comme la même chose. Si deux scénarios diffèrent, montrez la différence visuellement (plusieurs flèches convergeant vers les mêmes données, un cercle autour de la copie partagée), ne vous contentez pas de l’écrire dans le texte.
- Chaque nombre et chaque mot apparaissant dans l’image doivent avoir une source. Un nombre non expliqué précédemment („18“, „2 Mo“) bloque le lecteur ; soit il faut l’expliquer, soit le supprimer.
- Un problème propre à une solution particulière doit être placé dans le module de cette solution, pas dans l’introduction générale, pour que le lecteur ne pense pas que le problème est général.
- Utilisez des exemples concrets que le lecteur reconnaît, pas des symboles abstraits. Si des lignes, des points ou des petites barres bougent, le lecteur ne sait pas ce qu’ils sont (citation d’un lecteur : „Ces 4 barres de progression… je ne comprends pas ce qu’elles signifient“). Remplacez-les par une chose racontable : qui, à qui, a dit quoi (ex. : l’Agent du „système de paiement“ demande à l’Agent de la „plateforme de données“ : „Comment appeler l’interface de commande ?“, l’autre répond : „La documentation de l’interface a été envoyée“) ; si vous utilisez un symbole, utilisez quelque chose que le lecteur a déjà vu plus tôt (les lignes de la liste précédente), n’en inventez pas un nouveau. Un exemple bien développé vaut mieux que trois échanges abstraits ; si l’exemple est bon, ajoutez-en un autre différent, ne répétez pas le même exemple trois fois.
- Ne dessinez pas les couches et objets inutiles à cette étape. „Apparaître couche par couche“ ne signifie pas que chaque couche doit apparaître : si vous parlez de „le conteneur rend la mémoire à la VM“, ne dessinez pas l’hôte à ce moment-là, car le lecteur devra identifier une couche supplémentaire sans rien apprendre de plus (citation d’un lecteur : „Inutile de montrer l’hôte, cela complique“). Avant de dessiner, demandez : si je l’enlève, la phrase de cette étape tient-elle toujours ? Si oui, enlevez-le.
- Après avoir expliqué, répondez à la question „Et alors ?“. La dernière étape de chaque module ou la page de fin doit indiquer clairement ce que cela signifie pour le lecteur, où on en est (déployé / seulement en test / pas encore fait).
- Le niveau de profondeur est défini par le lecteur. Avant de commencer, écrivez „qui est le lecteur, que sait-il déjà, que ne lui importe-t-il pas“ : expliquer les bases à un initié est ennuyeux, donner trop de détails d’implémentation à un non-initié est trop spécifique.
Texte
- Par étape : une phrase (lead) + au maximum 2 à 3 points clés, gras réservé aux nombres ou mots conclusifs. Si le texte à gauche est trop long, supprimez les détails, placez-les dans la page de fin ou dans une petite note en bas à droite de l’image.
- Ne faites pas référence à des choses expliquées plus tard. Des expressions comme „ne plus stocker séparément“, „encore“, „de même“, „cette copie-là“, „comparaison“ doivent faire référence à quelque chose déjà apparu. Après avoir réorganisé l’ordre des sections, relisez le texte déplacé dans le nouvel ordre depuis le début.
- Expliquez le premier terme technique rencontré en une demi-phrase, et utilisez le même nom pour la même chose dans toute la page.
- N’utilisez pas de noms internes : numéros RFC, numéros de PR, noms de fichiers, noms de fonctions, noms de commandes, noms de machines internes. Exception : le lecteur est le développeur de ce code.
- Termes et „nombre + unité“ ne doivent pas être coupés : mettez-les entre
{{ }}, comme{{4 KB}},{{1,38 milliard de tokens}}. - Pied de page : indiquez „Mis à jour : mois/année · Vérifié sur la version X du code“. La page est un instantané d’un jour donné, le code change.
- Pour les déductions non testées, écrivez „déduction“, „à vérifier expérimentalement“ ; pour les nombres provenant d’autres sources, indiquez clairement la source („article“, „POC“, „sur main“).
Image
- Un même objet reste le même tout au long : un bloc de données „vole“ du disque à la mémoire, puis vole dans la VM, au lieu de disparaître ici et réapparaître là. Le lecteur s’appuie sur cela pour suivre le processus.
- Les couleurs ont une signification fixe, cohérente sur toute la page (par exemple : cyan = données, violet = programme, orange = action en cours, bleu = conclusion / rendu). La légende ne montre que les couleurs utilisées.
- Les mouvements ont aussi une signification fixe, cohérents sur toute la page (par exemple : tracer une ligne orange = envoyer une requête, un bloc de couleur qui vole = données livrées, un cercle orange = la copie partagée par tous, un groupe qui pâlit = inutilisé). Les mêmes types de mouvement ont la même vitesse : ceux qui parcourent une longue distance mettent plus de temps, ne les forcez pas à avoir la même durée.
- L’état est indiqué par la couleur, et seulement deux ou trois états : par exemple „bleu = en cours d’utilisation, gris = libéré“. Le lecteur peut compter d’un coup d’œil combien il y a de bleus et de gris, puis comprend quand plus tard „les gris sont récupérés“ ; n’utilisez pas à la fois la couleur, une icône et du texte pour dire la même chose.
- Le texte à lire ne bouge pas : si une phrase doit être transmise de A à B, laissez-la immobile près de l’expéditeur, et envoyez un petit marqueur le long du trajet ; le lecteur lit le texte fixe et regarde le marqueur suivre le chemin. Si le texte vole, le lecteur ne voit ni l’un ni l’autre.
- Bougez d’abord, puis arrêtez : l’action principale d’une étape doit être terminée dans les 60 % du temps, puis l’image se stabilise pour laisser le lecteur lire la phrase à gauche ; deux actions importantes ne se produisent pas en même temps ; un grand déplacement ne doit pas durer moins d’une demi-seconde, et un déplacement traversant toute l’image pas moins de 0,7 seconde, sinon l’œil ne suit pas.
- Comme ça vient, ça repart : les boîtes dessinées avec des lignes sont effacées par ces mêmes lignes ; ce qui vole arrive en volant et repart en volant. N’utilisez que deux ou trois techniques d’entrée/sortie sur toute la page, les fondus ne doivent pas être la valeur par défaut.
- Quand plusieurs lignes convergent vers une même cible, elles arrivent de directions différentes (une depuis la gauche, une depuis le haut, une depuis la droite), ne les alignez pas sur le même bord : elles finiront par se chevaucher ou passer derrière d’autres formes (citation d’un lecteur : „La ligne du téléphone et celle du client se chevauchent, et le téléphone lui-même cache la ligne du client“).
- Le sens est correct mais l’esthétique est médiocre, donc ce n’est pas fini (citation d’un lecteur à propos d’un nuage : „Le sens est bon, mais le nuage est trop laid et trop rigide“). Pour les formes clés (celles qui apparaissent plusieurs fois sur toute la page, ou sur lesquelles la dernière étape se termine), dessinez d’abord deux ou trois variantes côte à côte, choisissez-en une ; en regardant, demandez : les lignes ont-elles la même texture que les autres éléments de la page ? Les proportions sont-elles harmonieuses ? Les lignes se distinguent-elles de l’arrière-plan ?
- Les marqueurs de mise en évidence (cercles, flèches, petits textes orange) n’apparaissent que lorsqu’ils sont expliqués et disparaissent ensuite ; au plus tard au début de l’étape suivante, ils ne doivent pas être présents dans l’étape d’après. L’image à la fin de chaque étape doit être compréhensible seule (c’est
step-NN.png). - Pour mettre en évidence le partage / la même copie : plusieurs flèches convergent en une seule vers la même cible, avec en plus un cercle orange.
- „Supprimé“, „rendu“ doivent être montrés : la chose vole jusqu’à la section correspondante de la barre d’occupation, une fois posée, cette section se raccourcit ; ne la raccourcissez pas pendant qu’elle vole. La position de vol doit correspondre à la partie qui se raccourcit.
- Quand le schéma ne respecte pas l’échelle réelle, marquez „schéma“ et ne laissez pas la taille des cases suggérer une unité inexistante.
- L’imbrication des boîtes et les noms doivent correspondre à la réalité : avant de dessiner, faites une liste „objet → dans quel espace réseau / conteneur / processus / service il se trouve réellement“. Les conteneurs ou processus indépendants (sidecar, proxy) sont dessinés comme des boîtes parallèles, pas à l’intérieur du conteneur métier ; la boîte externe doit indiquer clairement ce qu’elle est („espace réseau d’un groupe de conteneurs“), et le nom de la boîte doit être celui utilisé par le lecteur („conteneur métier“, pas „conteneur principal“) ; si des choses ont le même nom, distinguez leur appartenance (quand deux services ont chacun un composant appelé sidecar, utilisez un nom complet fixe pour chacun), et ne mélangez pas sur l’image et dans la colonne de gauche.
- Les lignes doivent avoir le moins de coudes possible : les points d’extrémité doivent se trouver sur les bords opposés des deux boîtes, ne visez pas le centre de la boîte ; si les deux boîtes ont une hauteur qui se chevauche, tracez une ligne droite ; s’il faut un coude, un seul point de coude clair (un détour pour contourner un obstacle peut en avoir deux au maximum), et ce point de coude doit éviter les textes ; les paquets de données, les lignes rouges, etc. qui suivent le même chemin partagent ces points de coude. Les petits coudes seront interprétés par le lecteur comme „quelque chose de spécial ici“. La vérification
bendsdecheck.jsles signalera. - Placez les petites notes explicatives sur le bord de la boîte, pas sur les objets à l’intérieur.
- Le texte dans l’image ne doit pas être inférieur à 14 unités de canevas. Sur un ordinateur portable de 13 pouces, l’image sera réduite à environ 0,8x, et en dessous, c’est illisible ; la vérification
fontsizedecheck.jsbloque si la taille est inférieure à 11 px dans une résolution de 1280 × 720. Si cela ne tient pas, supprimez du contenu, ne réduisez pas la police. Le modèle propose également un „agrandissement“ (bouton en haut / touche F), qui est une option pour le lecteur, pas une solution pour un texte trop petit.
3. Retours courants (recevez ce feedback, corrigez ainsi)
| Feedback | Cause probable | Correction |
|---|---|---|
| „L’animation de cette étape ne se termine pas / la fin est problématique“ | Des images clés arrivent après la fin de l’étape, ou un fondu se produit exactement à la fin | Faites en sorte que toutes les actions de l’étape commencent avant T(id, 0.88) et s’arrêtent avant T(id, 1) ; check.js (élément still) signalera |
| „Le texte sort du cadre / la position est incorrecte“ | La boîte parente et son contenu ne commencent pas à se déplacer au même moment ; une image clé a été écrite qui ne change que la couleur et fixe la position | Utilisez les mêmes instants pour le parent et l’enfant ; marquez-les avec data-box / data-in, et utilisez l’élément contain pour vérifier image par image. Ne remplacez pas „dans le cadre“ par d’autres indicateurs (taille de police, transparence) |
| „Les étapes N et M se ressemblent“ | La différence n’est que dans le texte | Montrez la différence visuellement (voir ci-dessus : flèches convergentes + cercle) |
| „D’où vient X ?“ | Un nombre / une unité non expliquée dans l’image | Expliquez la source, ou retirez-la de l’image en ne la mentionnant que dans le „pourquoi“ |
| „L’ordre est incorrect, on devrait d’abord faire A puis B“ | Pas d’ordre causal / hiérarchique | Réorganisez le temps de cette étape selon „d’abord le niveau inférieur, puis le niveau supérieur“ ; en profitez pour vérifier aussi les autres étapes selon le même principe |
| „XX est étrange, jamais mentionné avant“ | Le texte fait référence à quelque chose expliqué plus tard | Grep „ne plus, stocker séparément, encore, de même, cette copie-là, comparaison“, vérifiez chaque occurrence que la chose référencée est déjà apparue |
| „Trop de texte / illisible / trop petit“ | Des détails entassés dans la colonne de gauche ; police de l’image inférieure à 14 | Réduisez à une phrase + points clés ; police de l’image à 14 ou plus, si cela ne tient pas, supprimez ; check.js (éléments fontsize, text) signalera |
| „En défilant depuis la page d’accueil, la première étape n’a pas d’animation / après rafraîchissement, pas d’animation“ | Logique d’entrée du moteur modifiée | Ne touchez pas aux lignes enteredFirst, pendingShow et au début du bloc B2 ; check.js (élément wheel) signalera |
| „Pourquoi ce coude ?“ (avec capture d’écran) | La flèche pointe vers le centre de l’autre boîte, ou les points de coude sont calculés indépendamment, créant un petit zigzag ; les paquets de données et les lignes sur le même chemin suivent des itinéraires différents | Placez les points d’extrémité sur les bords opposés, en ligne droite si possible, un seul point de coude maximum, les paquets de données et les lignes partagent le même point de coude ; check.js (élément bends) signalera. Vérifiez tous les liens de l’image selon le même principe |
| „X est-il un Y indépendant ? Dessiné dans Z, est-ce approprié ?“ „Ce bloc devrait plutôt s’appeler… serait-ce plus précis ?“ | L’imbrication des boîtes ne correspond pas à la réalité (sidecar dessiné dans le conteneur métier), ou le nom de la boîte est un nom interne | Dressez d’abord une liste „objet → appartenance réelle“, puis corrigez l’imbrication ; écrivez clairement sur la boîte externe ce qu’elle est, remplacez le nom par celui utilisé par le lecteur ; vérifiez toutes les boîtes similaires sur l’ensemble de la page |
Après avoir reçu un feedback, demandez-vous d’abord s’il s’applique aussi à d’autres étapes et corrigez-les en même temps, n’attendez pas que l’on vous les signale une par une.
4. Fichiers
| Fichier | Contenu |
|---|---|
assets/template.html | Modèle (moteur + exemple en 4 étapes) |
scripts/check.js | Script d’auto-test (10 éléments + captures) |
references/storyboard.md | Comment écrire un storyboard, un vrai storyboard de 12 étapes |
references/engine.md | Structure du modèle, utilitaires, techniques d’image, pièges, comment lancer l’auto-test |
references/lessons.md | Enregistrement des retours de plusieurs pages réalisées (origine des règles) ; quand une règle ne couvre pas un cas, cherchez ici le cas le plus proche |