IbrahimSobh/content-explainer-slide

Diapositive Explicative de Contenu

Construit une image qui raconte l'histoire d'un travail technique : ce qui a été remarqué, ce qui n'allait pas, ce qui a été fait et pourquoi chaque étape fonctionne, d'où vient chaque nombre, et ce qui a été accompli et appris.

La barre est 100 % claire et intuitive pour un ingénieur junior, pas 100 % détaillée. Cette barre vient de cycles de révision réels : chaque fois qu'un terme n'était pas défini, qu'un nombre n'avait pas d'origine visible, que la raison d'une étape était cachée dans une note de bas de page, ou qu'une carte avait une zone vide, le lecteur revenait avec « qu'est-ce que c'est ? », « d'où vient 30 ? », « pourquoi ça marche ? » — et la diapositive avait besoin d'un autre tour. Tout ce qui suit existe pour répondre à ces questions sur la diapositive avant que le lecteur ait à les poser.

Un exemple concret d'un plan de diapositive terminé (une expérience de « chirurgie de neurones » sur un réseau neuronal) se trouve dans references/worked-example.md. Lisez-le une fois avant de planifier votre première diapositive ; il montre à quoi ressemble chaque carte lorsque les règles sont appliquées.

Étape 0 — Demander le format de sortie, puis construire une fiche de faits

Demander le format (une fois, avant de dessiner)

Demandez à l'utilisateur quel format de sortie il souhaite, à moins qu'il ne l'ait déjà précisé :

• PNG via matplotlib (Python) — meilleur lorsque l'entrée contient des données, des modèles, des journaux ou des fichiers de résultats, car un script peut calculer chaque nombre sur la diapositive directement à partir de ces fichiers (pas de nombres saisis à la main). Exporte également une copie JPG.
• Page HTML/SVG rendue en PNG — meilleur lorsque l'entrée est uniquement du texte (un article, un document, des notes), ou lorsque la typographie et le soin de la mise en page importent plus que le calcul des nombres. Rendu en PNG avec Chrome/Edge sans tête.
• Les deux — même plan de diapositive, deux rendus.

Indiquez votre recommandation avec la raison (entrée de données → matplotlib ; entrée de texte → HTML). Si l'utilisateur ne peut pas être interrogé (exécution automatisée), choisissez selon cette règle et dites lequel vous avez choisi et pourquoi.

Construire la fiche de faits

Avant de concevoir quoi que ce soit, listez chaque fait que la diapositive pourrait utiliser. Pour chaque fait, enregistrez :

fait	valeur	mesuré sur (quelle donnée / quelle section)	source (fichier + script, ou page/tableau d'article)

Ensuite :

• Recoupez les faits les uns avec les autres et avec tout texte provisoire (un post, un résumé, un README). Résolvez chaque incohérence maintenant — une diapositive qui dit 38 alors que le post dit 36 détruit la confiance, et ces incohérences viennent généralement de deux endroits qui calculent « le même » nombre différemment (taille d'échantillon différente, seuil différent).
• Enregistrez la division des données : ce qui a été utilisé pour construire la méthode par rapport à ce qui a été gardé pour tester la méthode. La diapositive doit le dire, car « le résultat tient-il sur des données qu'elle n'a jamais vues ? » est la première question qu'un lecteur technique pose.
• Deux modes :
  • Mode données (résultats, modèles, CSV, logs existent) : le script de dessin les charge et calcule chaque nombre au moment du rendu.
  • Mode source (texte uniquement) : chaque nombre est copié depuis la source et la fiche de faits cite où (page, tableau, figure). N'inventez ni n'arrondissez les nombres au-delà de ce que la source énonce.

Enregistrez la fiche de faits à côté de la diapositive (<nom>_facts.md) afin que les modifications ultérieures restent cohérentes.

Étape 1 — Trouver l'histoire (3 à 6 cartes numérotées)

Écrivez une phrase répondant à chaque question. Chaque réponse devient une carte :

1. Découverte / contexte — ce qui a été remarqué, ou quel est le cadre.
2. Problème — ce qui ne va pas ou manque, mesuré. S'il y a plusieurs problèmes, nommez-les (Problème A, Problème B). Indiquez ce qui est ciblé et ce qui n'est délibérément pas ciblé, avec la raison — un lecteur qui voit un élément faible dans le graphique et aucune explication suppose une erreur.
3. Méthode — la recette pour un cas, sous forme d'étapes.
4. D'un cas à tous les cas — comment la recette a été appliquée partout, les règles qui ont décidé combien, et les comptes. Associez chaque correction au problème qu'elle résout (« Correction A → Problème A »).
5. Résultat + leçon — ce qui a changé, notre degré de certitude, ce que cela enseigne.

Fusionnez les cartes qui disent la même chose (les cartes redondantes ont été supprimées à chaque révision). Pour une petite entrée, les cartes 3 et 4 peuvent fusionner, ou la diapositive peut avoir 3 cartes : problème → méthode → résultat. Jamais plus de 6 — au-delà, c'est un jeu de diapositives, pas une diapositive.

Étape 2 — Titre

Une ou deux lignes en haut : un fait surprenant + l'action entreprise, par exemple « N des M parties ne faisaient rien. Alors elles ont reçu un travail. » Le titre est ce qui fait que quelqu'un arrête de défiler ; les cartes sont ce qui le fait lui faire confiance. Les nombres du titre proviennent de la fiche de faits / des variables du script, jamais saisis à la main.

Étape 3 — Squelette de carte (identique pour chaque carte)

• Numéro + couleur d'accentuation. Chaque carte a un grand numéro (1–5) et sa propre couleur d'accentuation, utilisée pour sa bordure et ses surlignements. Les nombres donnent l'ordre de lecture ; les couleurs permettent aux cartes suivantes de faire référence aux précédentes (« les 11 détecteurs de la carte 4 »).
• Titre = la question à laquelle la carte répond.
• Une phrase de conclusion en gras = la réponse.
• Une figure principale. La carte méthode peut utiliser une grille de cellules d'étapes ; la carte résultat peut utiliser un graphique plus un panneau d'explication.
• Étiquette de données — quelles données cette carte utilise et pourquoi ces données (« 18 000 des 60 000 images d'entraînement (30 %) — le reste conservé inaperçu pour que la vérification finale soit juste »).
• Courte note de bas de page — mises en garde uniquement. Le raisonnement ne va jamais dans la note de bas de page (voir Étape 4).

Étape 4 — Carte méthode : QUOI / image / cellules POURQUOI

Divisez la méthode en 3 à 5 cellules numérotées (une grille 2×2 lorsqu'il y en a 4). Chaque cellule a les trois mêmes bandes, de haut en bas :

1. Légende (QUOI) — une action concrète qui dit ce qui est comparé à quoi : « Comparer une NOUVELLE image (qu'elle n'a jamais vue) avec le motif de l'étape 2 », pas « ça correspond ».
2. Image — construite à partir d'exemples réels issus des données ou de la source : entrées réelles, le résultat intermédiaire réel, les scores réels. Les exemples réels sont ce qui rend une étape abstraite crédible ; une icône générique n'enseigne rien.
3. Boîte POURQUOI — pleine largeur, hauteur fixe, stylisée visiblement (fond teinté, étiquette « POURQUOI ? »). Elle explique pourquoi l'étape fonctionne.

Le POURQUOI doit être dans l'image, bien en évidence. Lors des révisions, le raisonnement placé dans les notes de bas de page a toujours été manqué et le lecteur a dû demander à plusieurs reprises. À l'intérieur des cellules, répondez aux questions que les lecteurs poseront :

• Pourquoi ce choix plutôt que le choix évident ? (par ex. pourquoi soustraire la moyenne de la classe correcte)
• Qu'est-ce que cela n'affecte PAS, et pourquoi pas ? (par ex. « cela ne peut que baisser '3' ; si une autre classe gagne déjà, rien ne change »)

Montrez le mécanisme sous forme d'avant → après : un petit panneau de scores/états avant, une flèche, le panneau après, avec ✓/✗ sur le gagnant et une courte note sur la flèche (« le 2e plus haut gagne »). Si le titre d'un panneau ne tient pas en dessous, mettez-le à côté.

Si une image simplifie la réalité (elle montre des pixels, alors que le vrai calcul utilise des caractéristiques internes), dites-le dans la note de bas de page — l'honnêteté sur la simplification coûte une ligne et évite un commentaire « ce n'est pas comme ça que ça marche ».

Marquez un exemple concret comme « Exemple : » et énoncez la règle générale (« même recette pour les 30 détecteurs »), sinon les lecteurs pensent que la méthode ne couvre que ce cas.

Étape 5 — Rendre chaque nombre traçable

• Montrez l'origine de chaque nombre sous forme de chaîne visible : « 21 exemples → 3 styles → 3 détecteurs », « 11 + 19 = 30 sur 36 (6 de réserve) ». Les totaux doivent visiblement s'additionner, et les restes doivent avoir une raison.
• Énoncez les règles de sélection et seuils qui ont produit les comptes (« un style nécessite ≥2 exemples », « erreurs avec <3 exemples ignorées car trop peu pour apprendre »).
• Si les données proviennent de sources différentes (étiquetées vs. extraites, mesurées vs. estimées), montrez-le visuellement (barres foncées vs. claires) avec une légende.
• Expliquez toute notation la première fois qu'elle apparaît (« ×N = N détecteurs de style pour cette erreur »).
• En mode données, le script calcule chaque nombre ; les chaînes de texte utilisent les variables (f-strings / valeurs de template). Les nombres saisis à la main se désynchronisent des données — cela a déjà causé une diapositive erronée.

Étape 6 — Résultat honnête, chaque changement expliqué

• Avant → après sur des données jamais utilisées pour construire la méthode ; confirmez sur un deuxième ensemble non utilisé lorsqu'il en existe un.
• Donnez les gains et les pertes (« 34 corrigés, 9 cassés »). Un résultat avec seulement des gains semble choisi sur mesure.
• Statistiques en mots simples (« environ 6 sur un million par hasard »), avec la forme technique en petit ou dans la note de bas de page.
• Un graphique de changement par élément (après − avant, coloré positif / négatif / zéro) plus un panneau « pourquoi chaque changement » : pourquoi les gains se sont produits, pourquoi les pertes se sont produites, tout effet secondaire bonus. Lister une perte sans sa raison invite à la pire interprétation.

Étape 7 — Mots simples et cohérents

• Définissez chaque terme à sa première utilisation en quelques mots simples, ou remplacez-le par un mot simple.
• Un mot par concept sur toute la diapositive (« prédit » partout, jamais parfois « répondu »).
• Pas de surnoms internes (« Ensemble A », « le twist », « effet secondaire chanceux », « ×3 ») sauf s'ils sont définis sur la diapositive.
• Chaque affirmation doit correspondre à son graphique. Si le graphique montre quelque chose d'étrange que le texte n'aborde pas, abordez-le.

Étape 8 — Légendes et couleurs

• Chaque couleur, nuance, flèche et symbole est expliqué là où il apparaît. Les images divergentes reçoivent « rouge = seulement dans X, bleu = seulement dans Y ».
• Une signification de couleur sur toute la diapositive : par ex. rouge = problème/supprimé, vert = corrigé/bon, gris = neutre. Les couleurs d'accentuation des cartes sont séparées de ces couleurs sémantiques.
• Les éléments groupés (styles d'une même erreur, variantes d'une même étape) se trouvent dans des boîtes visibles afin que les groupes ne se mélangent pas.

Étape 9 — Bannières de conclusion et de leçon

• Bannière de conclusion (teinte verte) : ce qui a été montré, y compris sa taille et ses limites (« gain petit mais réel qui se maintient sur de nouvelles données »).
• Bannière de leçon (bas de la diapositive) : ce que le lecteur peut emporter pour d'autres problèmes.

Étape 10 — Mise en page

• 16:9 (par ex. 16×9 pouces à 150 dpi, ou un canevas 1600×900 px). Les cartes se lisent de gauche à droite dans l'ordre narratif.
• Dimensionnez les cartes par leur contenu — la carte méthode est généralement la plus large. Pas de grandes zones vides : si une carte a de l'espace libre, élargissez son graphique ou déplacez son panneau de texte dans l'espace.
• Pas de texte qui se chevauche ; les étiquettes restent à l'intérieur de leurs boîtes. Coupez les longues lignes plutôt que de réduire les polices en dessous de la lisibilité sur téléphone (≈7,5 pt à 16×9 pouces est le minimum).
• Consultez references/matplotlib-recipes.md (PNG) ou references/html-recipes.md (HTML) pour le code de mise en page. scripts/slide_kit.py fournit des helpers matplotlib (cartes, cellules d'étapes, boîtes POURQUOI, panneaux de scores avant/après, bannières, export PNG+JPG) — importez-le plutôt que de les réécrire.

Étape 11 — Rendu, inspection, correction, répétition

1. Générez l'image.
2. Regardez l'image réelle — ouvrez le PNG et zoomez sur chaque carte (recadrez-la si nécessaire). Le code qui « devrait » tenir ne tient souvent pas ; les chevauchements et le texte coupé ne sont visibles que dans le rendu.
3. Parcourez references/checklist.md carte par carte, en tant qu'ingénieur junior la voyant pour la première fois.
4. Corrigez, re-rendez, re-vérifiez. Ne montrez pas à l'utilisateur une diapositive qui échoue à la liste de vérification.

Étape 12 — Variantes et vérification finale

• Version détaillée pour les lecteurs techniques (tous les nombres). Proposez une version simple pour un large public : même histoire, moins de nombres exacts.
• Exportez une copie JPG (sans transparence) pour LinkedIn/X.
• Vérifiez toute affirmation ou citation externe qui apparaît sur la diapositive ou dans un post associé avant publication ; signalez toute affirmation que vous n'avez pas pu vérifier.
• Livrez : le PNG (+ JPG), le script de dessin ou la source HTML, et la fiche de faits. Mentionnez que linkedin-arabic-science-post, tweet-post ou figure-animator peuvent produire un post ou une version animée à partir de la diapositive terminée.