ruinosus/chalk-talk

chalk-talk : expliquer en dessinant

Vous réalisez une explication dessinée à la main : une recette dans un court texte (.chalk) que le lecteur de cette compétence dessine trait par trait, avec des chapitres, une courte narration et, lorsqu'il y a une quantité réelle, une valeur que l'utilisateur manipule. Vous rédigez uniquement la recette ; scripts/build.mjs la vérifie et construit un seul fichier HTML contenant tout. N'écrivez ni ne copiez jamais le lecteur vous-même. Les chemins ci-dessous sont relatifs au dossier de cette compétence.

1. Dessinez d'abord

Pour une demande ordinaire (« explique X en dessinant », « dessine comment fonctionne Y ») ne demandez pas et ne montrez pas de plan : dessinez. Décidez vous-même des trois choses dont un dessin a besoin, et dites-les lorsque vous les livrez :

• l'accroche : une chose de la vie quotidienne à laquelle l'idée est liée, que le public a vue ou faite et qui peut être dessinée avec peu de formes (une facture de carte, un arrêt de bus, une file d'attente au café) ;
• à qui cela s'adresse : ce que dit la demande, sinon un adulte curieux ;
• la valeur que l'utilisateur manipule : une quantité réelle dans l'idée (le taux mensuel, les personnes arrivant par minute), ou aucune.

Un dessin pour présenter, convaincre, décider, documenter ou raconter ce qui s'est passé (un pitch, une architecture pour un client, un post-mortem) relève de back-of-napkin, lorsqu'il est installé ; cette compétence enseigne.

Demandez d'abord — une fois, tout ensemble, et seulement ce qui manque — lorsque c'est pour une classe, des étudiants, une conférence ou un cours (voir « Pour une classe »), lorsque la demande pourrait signifier deux choses différentes, ou lorsque la personne demande à voir le plan d'abord.

Le dessin comporte quatre parties, un chapitre chacune : l'accroche sous forme de question (« pourquoi 1 000 € deviennent-ils 1 974 € ? ») ; décomposez (la chose réelle, simplement, et ce qui est caché dedans) ; l'idée (la règle, le flux ou l'argument, avec la valeur qui se déplace) ; la conclusion (un point fort sur le résultat et où la comparaison s'arrête).

2. Rédigez la recette

Écrivez <id>.chalk avec les lignes ci-dessous — cela couvre le dessin habituel ; vous n'avez pas besoin de lire quoi que ce soit d'autre d'abord. Le papier fait 900 × 560 (size 900x780 crée un tableau plus haut), x croît vers la droite et y vers le bas, le at d'un accessoire est l'endroit où il se tient (son centre inférieur) ; gardez 30 px des bords. # Titre ouvre un chapitre et > phrase est la narration : les deux passent à l'étape suivante. Un point est x,y sans espace ; une expression est entre guillemets et peut utiliser les paramètres et variables.

C'est un seul tableau : un chapitre n'efface jamais le papier. Tout ce qui est dessiné reste, comme la craie sur un tableau noir, alors planifiez l'ensemble du tableau avant d'écrire et donnez à chaque partie son propre emplacement — le titre une fois en haut, l'accroche et la chose réelle dans la moitié supérieure, l'idée en dessous ou à côté, la conclusion dans ce qui reste. Ne dessinez jamais deux choses au même endroit ; 12 à 25 étapes suffisent généralement.

Le haut :

title Juros compostos ↔ a fatura do cartão
locale pt-BR
size 900x560
param taxa "juros ao mês (%)" 1..15 step=1 = 8
switch atraso "pagar com atraso" off
var f = "1 + taxa/100"
learning goal "Ver o juro sobre o juro crescer mês a mês."

Écrivez les quatre lignes learning — goal, question (une à méditer), answer (concrète) et caveat (ce qui a été simplifié) — et réglez locale sur la langue de l'utilisateur, avec tout le texte dans cette langue.

Les personnes et les choses sont des accessoires : person, person-sitting, person-pointing, house, car, bus, coin, phone, document, server, bank, cloud, queue, desk, computer, clock, lock, money-arrow, tree, school, hospital, factory, truck, cart, safe, bulb, gear, database, robot, ship, container, warehouse, box, pallet, shop, shelf, field, cup, function, api-gateway, cache, cluster, board, book, pencil. Un person prend mood= happy, sad, surprised, worried ou idea.

person ana at 150,330 "Ana" mood=worried
text "R$ 1.000 viram quanto?" at 40,64 size=36
text "paga só o mínimo" right-of ana gap 16 align=start
ana thinks "e se eu atrasar?" side=above width=200
ana -> banco "paga" -> loja "repassa"
arrow 60,350 -> 840,350 color=#2E8F62 stroke=3
highlight 90,500 -> 810,500 thickness=24

Placement sans calculer de coordonnées — privilégiez ces méthodes lorsque les pièces sont côte à côte ou se suivent. Une chain est des choses qui se transmettent quelque chose : réparties sur le papier, chacune jointe à la suivante, avec les longues flèches si demandé :

chain at 40,190 forward="o café desce" back="pedidos sobem"
  field fazenda "fazenda"
  truck caminhao "transporte"
  cup cafe "cafeteria"
  person voce "você"
row at 470,150 gap 14
  repeat 3: coin size 44
repeat 3: coin at "100 + i*60",400 size 40

Quelque chose qui continue de bouger sur place, à partir de cette étape — spin, drive, steam (volutes au-dessus), talk, pulse ou float, et stop. Uniquement là où le mouvement dit quelque chose (le camion part, la vapeur au-dessus de la tasse), un ou deux par dessin :

animate caminhao drive

Un emoji animé prêt à l'emploi — uniquement lorsque la personne en demande un, et un par leçon au maximum (il est poli, pas à la craie) : celebrate, think, surprised, ok, idea ou time, centré sur at ; ou ./file.json, un fichier Lottie donné par la personne, à côté de la recette. La construction l'intègre dans le fichier, avec son crédit — et le fichier passe d'environ 340 Ko à environ 610 Ko (le lecteur et l'animation) :

lottie celebrate at 720,180 size=120

Nombres qui suivent la valeur :

counter at 470,270 "1000*f^6" "R$ {v:0} em seis meses" size=34
bars box 90,320,440,180 values 1000,"1000*f^3","1000*f^6" labels hoje,"3 meses","6 meses" format="R$ {v:0}"
plot "1000*(1+taxa/100)^x" domain 0..12 range 0..4000 box 480,120,360,240
when atraso:
  text "multa de 2%" at 600,100 color=#C8442C

Une chose qu'aucun accessoire ne dessine : créez-la sur une grille 0–100 (nombres entiers, y vers le bas ; elle se tient à 50,100), puis utilisez son nom :

define xicara
  polygon 24,48 76,48 70,90 30,90 fill=#FFFFFF
  curve 74,56 90,62 72,80
xicara minha at 450,300 "minha xícara"

Attente de l'utilisateur, et un quiz (tous deux pour une classe) :

pause ask "Quanto vai virar a fatura em seis meses?"
quiz "Se a taxa dobra, a fatura em seis meses…"
  * mais que dobra o juro -- é juro sobre juro
  - só dobra -- isso seria juro simples

Gardez : 8 à 40 étapes sur un seul tableau ; une narration courte uniquement lorsque l'idée change ; titres 36 à 44, étiquettes 24 à 34, rien en dessous de 22 ; couleurs graphite (par défaut), #2F5BEA, #C8442C, #2E8F62, #8C8578, marqueur #FFE45C, trois accents au maximum ; faits et nombres justes — n'inventez jamais une citation ou un chiffre. Les autres étapes (circle, curve, card, table, axis, timeline, brace, note, move…) se trouvent dans references/text.md ; ce que chacune dessine, dans references/recipe.md. Ouvrez-les uniquement lorsque vous avez besoin d'une étape qui n'est pas ci-dessus ou que le message de construction ne résout pas une erreur.

Si la personne donne un diagramme Mermaid, conservez-le tel quel, ajoutez les lignes %% title …, %% # chapitre et %% > narration et enregistrez-le sous <id>.mmd (references/text.md montre comment). Enregistrez la recette dans le dossier où la personne travaille, ou, lorsqu'un dossier de sorties existe pour les fichiers que la personne télécharge (sur claude.ai, /mnt/user-data/outputs), là.

3. Construire et vérifier

node scripts/build.mjs <id>.chalk

Cela écrit <id>.html à côté de la recette et affiche :

• ✗ text: line N … ou ✗ contract: … (exit 1, rien écrit) : corrigez cette ligne comme le message le dit, comme l'exemple en dessous le montre.
• ! review … (exit 3) : dessiné, mais quelque chose sort du papier, un texte en recouvre un autre ou une ligne croise un texte. Corrigez et reconstruisez avec --snapshots : cela écrit aussi <id>.snapshots/<id>.contact-sheet.png — chaque chapitre à chaque réglage des valeurs. Ouvrez cette image et corrigez ce que la revue a nommé et tout ce qui ne se lit pas correctement (une figure qui n'est pas reconnaissable, un coin surchargé, un texte trop petit).
• ✓ review, ou • review … the page checks itself when opened (pas de navigateur ici) : terminé.
• • figures … defined : la recette crée une figure avec define, et la revue la mesure uniquement — ouvrez la contact sheet une fois et vérifiez que la figure se lit comme la chose qu'elle devrait être.
• ✗ review not checked: … : terminé, mais dites à la personne que le dessin n'a pas été vérifié.

Au maximum deux tours de corrections ; puis livrez et dites en termes simples ce qui reste (« avec 15 % l'étiquette touche le titre »).

Plusieurs leçons (un cours) : une recette chacune, construites ensemble — node scripts/build.mjs one.chalk two.chalk --out course.html --title "Le cours". Pour un README (ou partout où seule une image va), lorsque demandé : node scripts/build.mjs <id>.chalk --svg écrit <id>.svg, une image qui se dessine elle-même ; la leçon reste le .html.

4. Livrer

Donnez le chemin du fichier .html (ou le fichier lui-même là où la personne télécharge des fichiers) et, en une ligne, ce que vous avez choisi et une offre de le modifier : « Je l'ai lié à une facture de carte de crédit, pour quelqu'un qui n'a jamais étudié les intérêts, avec le taux mensuel à manipuler — voulez-vous une autre accroche, un autre public ou quelque chose de changé ? » Puis une phrase sur quoi regarder (« appuyez sur Suivant ; au chapitre 3, déplacez le taux »). Le fichier s'ouvre hors ligne, avec des chapitres, les valeurs à côté du papier, et le téléchargement PNG, SVG, GIF et WebM — il peut être envoyé par e-mail ou sur un projecteur.

Pour le présenter (une conférence, un cours sur un projecteur) : construisez avec --present — la page s'ouvre sur un chapitre à la fois, en plein écran et les notes du présentateur avec la première clé ; un clic sur PageDown avance. Un PowerPoint, lorsque demandé : --pptx (une diapositive par chapitre ; steps agrandit le dessin clic par clic, video intègre chaque chapitre se dessinant lui-même), avec la narration comme notes du présentateur.

Pour une classe

Lorsque le dessin est pour une classe, des étudiants, une conférence ou un cours, demandez d'abord, en un message : jusqu'à trois accroches, la meilleure en premier, chacune avec une ligne sur pourquoi elle fonctionne pour ce public (references/hooks.md), qui exactement est le public, et quel chiffre les étudiants peuvent manipuler. Ne demandez jamais ce qui a déjà été dit. Montrez ensuite le plan en quatre parties en quelques lignes et attendez le feu vert (« ok », « go »). La recette ajoute theme chalkboard, un pause ask ouvrant la partie qui y répond, et un quiz à la fin.

Pas d'exécution de code (un artefact à la place)

Lorsque vous ne pouvez pas exécuter de code mais pouvez afficher un artefact HTML, mettez la recette dans cette petite page — rien d'autre — et montrez-la. Le lecteur se charge depuis le CDN et vérifie la recette lui-même :

<!doctype html>
<meta charset="utf-8">
<title>TITRE DE LA LEÇON</title>
<script type="text/chalk-talk" id="chalk-recipe">
LA RECETTE EN TEXTE
</script>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/player.js"></script>

Si la page indique que la recette n'a pas pu être ouverte, corrigez la ligne qu'elle nomme.

Modifier plus tard

« Rends la flèche bleue », « ajoute une deuxième personne », « utilise 5 % à la place » : modifiez uniquement ce qui a été demandé, gardez le reste, reconstruisez et dites ce qui a changé. Une accroche ou un public différent est un nouveau dessin.

Jamais

• Ne modifiez jamais assets/ ou scripts/contract.mjs : ils sont générés.
• Ne mettez jamais de HTML, liens, scripts ou images dans une recette : les textes sont en texte brut, les couleurs sont hexadécimales ou nommées.
• N'écrivez jamais de script pour générer la recette : écrivez-la vous-même (les expressions et repeat font l'arithmétique).
• Sans exécution de code, n'écrivez jamais à la main le lecteur, un SVG ou une image du dessin : utilisez la petite page ci-dessus. Si vous ne pouvez ni exécuter de code ni montrer un artefact, dites-le et donnez la recette.