rzhang569/guide-d-étude

Guide d'étude

Vous produisez une page HTML autonome par examen, construite à partir d'un dossier de cours composé de fichiers simples via scripts/build.py. La page comporte trois parties :

• Notes, une section par cours. Chaque affirmation cite une page de diapositive. Chaque sujet est accompagné de boîtes en langage clair, d'exemples travaillés, de figures et de boîtes rouges « piège ». Une boîte d'exercices à la fin de chaque section permet à l'étudiant de se tester immédiatement après la lecture.
• Un centre d'exercices avec quatre onglets :
  • une banque d'exercices avec retour instantané et explication pour chaque option ;
  • des réponses courtes étape par étape avec crédit partiel ;
  • des examens blancs chronométrés tirés de leur propre pool dans les proportions de l'examen réel ;
  • un carnet d'erreurs qui se remplit automatiquement.
• Un rapport de progression, que la page conserve pour vous. Vous le lisez plus tard et rédigez de nouveaux exercices ciblant ce que l'étudiant a réellement mal compris.

Le moteur (assets/engine.js) et les styles (assets/page.css) sont terminés et testés, votre travail porte donc sur le contenu et les questions. La majeure partie de ce qui rend une page utile se trouve dans les fichiers de référence ; lisez-les lorsque vous atteignez cette étape.

Quand vous êtes sur le point de...	Lisez
rédiger les sections de cours	references/content-standard.md
rédiger ou auditer des questions, ou calibrer l'examen blanc	references/question-bank.md
vérifier un nom de champ, le format de progression ou la documentation de la base de données	references/data-format.md

examples/demo/ est un petit cours complet (PROB 101 fictif, trois cours). En cas de doute sur l'apparence de quelque chose, copiez le modèle à partir de ses sources : sections/*.html, practice.json, mock.json et short.json.

Ne lisez pas assets/engine.js, assets/page.css ni aucun fichier review.html construit. build.py les intègre, ils contiennent des dizaines de milliers de jetons, et rien ne nécessite vos modifications.

Dans les commandes ci-dessous, <skill-dir> correspond au dossier qui contient ce SKILL.md. Si python3 n'est pas trouvé (courant sous Windows), utilisez python ou py -3.

1. Déterminer ce qu'est l'examen

Obtenez ces faits avant d'écrire quoi que ce soit. Recherchez-les lorsque vous le pouvez, et demandez à l'étudiant uniquement ce que vous ne pouvez pas trouver :

• Examen : date et heure, durée en minutes, cours concernés, format et matériel autorisé. Le format signifie les types de questions, leur nombre et leurs points. Le matériel signifie des feuilles de notes, une calculatrice ou rien.
• Sources : diapositives (PDF ou liens), lectures, site web du cours, ainsi que toutes les questions d'entraînement officielles, résultats de quiz ou examen blanc.
• Étudiant : la langue souhaitée pour la page (lang : zh ou en pour l'interface ; rédigez le contenu dans leur langue), et leur niveau de connaissances. Un étudiant qui dit « je suis perdu » a besoin de boîtes en langage clair sur presque tous les sujets.

Si vous pouvez naviguer, faites vos propres recherches sur le cours : la page du calendrier, le syllabus et les résultats de quiz publiés. Cherchez des schémas utiles à communiquer à l'étudiant, comme « les questions de contrôle en classe viennent juste après une diapositive spécifique » ou « la banque officielle indique qu'elle utilise le même format que l'examen ». Placez les informations logistiques dans la section hero de la page.

Vérifiez la politique IA du cours dans le syllabus. Certains cours interdisent le matériel d'étude généré par l'IA ou interdisent l'aide de l'IA pour les travaux notés. Si la politique interdit cela, informez-en l'étudiant avant de construire. Ne mettez jamais les réponses aux devoirs notés sur la page.

2. Calibrer l'examen blanc sans révélations

Les étudiants souhaitent souvent conserver l'examen blanc officiel pour une seule tentative chronométrée. Dans ce cas, ne lisez pas ses questions ; mesurez-le plutôt :

python3 <skill-dir>/scripts/count_exam.py echantillon_examen.pdf

Le script n'affiche jamais le texte des questions, options ou scénarios. Il affiche :

• le nombre de pages et de questions, ainsi que les options par question ;
• les valeurs en points, la limite de temps et les instructions de couverture (calculatrice, notes) ;
• les en-têtes de parties et les plages de questions partageant un scénario (« Questions 11–14 … ») ;
• les numéros des questions qui renvoient à du contenu antérieur.

Utilisez la sortie pour définir les sections de l'examen blanc (types et nombres) et la limite de temps. Une question qui renvoie à du contenu antérieur, comme une réponse courte réutilisant un scénario précédent, appartient à ce scénario lorsque vous décrivez la structure de l'examen.

Si le script ne peut pas vous renseigner sur quelque chose, signalez-le comme inconnu et demandez à l'étudiant de regarder la page de couverture. N'écrivez pas votre propre outil qui imprime des mots ou des nombres provenant de l'intérieur des questions. Même un « total » ou « % » isolé donne un indice sur le sujet d'une question, et les nombres dans une équation révèlent la question.

Demandez avant d'ouvrir un échantillon ou un corrigé. Même lorsque l'étudiant autorise la lecture, utilisez-le uniquement pour l'étalonnage (structure, difficulté, style). Ne copiez jamais ses questions ou scénarios dans la page.

3. Configurer le dossier du cours

python3 <skill-dir>/scripts/build.py --init <course-dir>

Ceci copie le cours de démonstration. Modifiez ensuite course.json :

• title, lang et lectures. Les étiquettes de cours sont exactement ce que les questions et les groupes utilisent, par ex. "L1" ou "L5–L6".
• storageKey : unique par cours et par examen, par ex. "bio201-mt1". La progression est stockée sous cette clé, donc ne la changez jamais une fois que l'étudiant a commencé.
• mock.sections : une entrée par type de question, dans l'ordre de l'examen, avec des nombres correspondant au document réel.
• mock.minutes : limites de temps parmi lesquelles choisir. Incluez la durée réelle ; si l'examen blanc omet les longues questions, proposez également une durée proportionnellement plus courte.

Supprimez les sections et questions de la démo au fur et à mesure que vous les remplacez. Voir references/data-format.md pour tous les champs.

4. Rédiger les sections

Écrivez un fichier par cours dans sections/ (10-l1.html, 20-l2.html, …), plus 00-hero.html pour la logistique et une liste finale de pièges. Chaque cours est une <section class="part" id="...">. Sa boîte d'exercices apparaît automatiquement lorsqu'un groupe d'exercices pointe vers cet id avec "sec".

references/content-standard.md contient la recette complète et le HTML pour chaque composant. En résumé : citez chaque affirmation, ouvrez les cours difficiles avec un glossaire et des analogies, donnez à chaque sujet un résumé d'une ligne, un exemple concret avant toute formule, une boîte en langage clair, une figure là où une image aide, et une boîte piège pour ce que les questions vrai/faux modifient.

5. Rédiger les questions

Il y a trois banques. references/question-bank.md contient les règles et la liste de contrôle d'audit.

• practice.json : 8 à 15 questions par cours. Mélangez choix unique, vrai/faux, sélection multiple et remplissage, ainsi qu'une flashcard occasionnelle. Chaque option a sa propre explication.
• mock.json : ses propres questions, jamais de copies des exercices d'entraînement. Visez environ deux fois ce qu'un document tire de chaque type, de sorte que les documents répétés diffèrent. Correspondent au style de l'examen réel.
• short.json (optionnel) : versions étape par étape des types de réponses courtes de l'examen. Chaque étape est un remplissage tolérant, un choix ou une auto-vérification par rapport au modèle de réponse.

6. Construire et vérifier

python3 <skill-dir>/scripts/build.py <course-dir>

Les erreurs arrêtent la construction. Les avertissements proviennent des vérifications de la banque de questions ; corrigez-les sauf si vous avez une raison de ne pas le faire. Ils signalent des motifs tels que :

• la bonne réponse est l'option la plus longue dans trop de questions ;
• une lettre est la réponse affichée trop souvent ;
• chaque sélection multiple a le même nombre de réponses ;
• une question d'examen blanc est une question d'entraînement avec de nouveaux nombres.

Ajoutez --strict pour faire en sorte que les avertissements arrêtent la construction avec le code de sortie 2 (la page est toujours écrite), afin que vous puissiez continuer à corriger jusqu'à ce qu'elle soit propre. Ouvrez ensuite <course-dir>/review.html dans un navigateur et vérifiez :

• la console n'affiche aucune erreur et les formules s'affichent correctement ;
• répondre à une question d'entraînement, à une étape de réponse courte et à un examen blanc complet fonctionne ;
• à 375 px de largeur, rien ne fait défiler la page horizontalement (les figures et les tableaux défilent dans leurs propres boîtes) ;
• aucun texte dans une figure ne chevauche une ligne, une pointe de flèche ou un autre texte (faites une capture d'écran).

7. Livrer

• Local (tout agent) : donnez le chemin du fichier. La progression est sauvegardée dans le localStorage de ce navigateur. Le bouton Exporter la progression dans le centre d'exercices donne à l'étudiant un JSON à coller pour vous.
• Artefact claude.ai (Claude uniquement ; expérimental, pas encore testé de bout en bout) : publiez le HTML construit et accordez la capacité db. Si window.claude.use("db") est disponible, le moteur synchronise la progression avec les documents progress/practice et progress/mock et conserve un résumé dans progress/report. Avant de vous y fier, répondez à une question sur la page publiée et lisez progress/report en retour. Si le document est manquant, dites à l'étudiant d'utiliser Exporter la progression à la place.

Dites à l'étudiant en deux ou trois lignes comment utiliser la page : lire une section, faire sa boîte d'exercices, les examens blancs vers la fin et le carnet d'erreurs la veille.

8. Boucler la boucle

Lorsque l'étudiant revient, lisez sa progression avant de changer quoi que ce soit. Utilisez le JSON exporté qu'il colle ou envoie (son champ report), ou le document progress/report de la base de données si la synchronisation d'artefact fonctionne. Le rapport liste :

• la précision au premier essai par cours ;
• chaque question d'entraînement ratée avec ce que l'étudiant a répondu et la bonne réponse ;
• les étapes de réponse courte que l'étudiant a manquées ;
• l'historique des examens blancs, plus les questions erronées et signalées du dernier document.

Ensuite :

1. Nommez les points faibles en quelques lignes. Comptez les cours en dessous d'environ 80 % de précision au premier essai, les idées fausses répétées, et les étapes de réponse courte qui échouent systématiquement. Comptez également les questions signalées comme « incertain » mais répondues correctement ; ce sont aussi des connaissances fragiles.
2. Rédigez de nouveaux exercices pour chaque point faible. Reposez le même concept avec des mots, nombres ou scénarios différents ; ne répétez jamais la question qu'ils ont manquée. Ajoutez-les à practice.json avec de nouveaux identifiants, et à mock.json si le pool d'examens blancs y est insuffisant.
3. Corrigez l'explication, pas seulement les questions. Si une idée fausse se répète, la section l'explique probablement mal. Ajoutez une boîte en langage clair, un exemple travaillé ou une figure ciblant exactement cette confusion.
4. Reconstruisez, puis dites à l'étudiant ce qui a changé et où.

Préserver la validité de la progression enregistrée lors des modifications

Les enregistrements sont indexés par storageKey, identifiant de question id et index d'option d'origine. Donc :

• conservez le storageKey et les identifiants existants ;
• ne réorganisez, n'insérez ni ne supprimez d'options dans les questions qui ont reçu une réponse (ajoutez plutôt une nouvelle question) ;
• ne réutilisez pas un ancien identifiant pour une question différente ;
• si le sens ou la réponse d'une question change, donnez-lui un nouvel identifiant et supprimez l'ancien. Les enregistrements pour les identifiants supprimés sont ignorés, pas mal interprétés.

Le moteur mélange l'ordre d'affichage des options avec une graine provenant de l'identifiant, donc les index stockés restent corrects. Pour changer la lettre sous laquelle une réponse est affichée, définissez "show" (voir references/data-format.md) au lieu de réorganiser les options. Corriger les fautes de frappe ou le libellé dans les énoncés et les explications est toujours sûr, tout comme modifier le HTML des sections.

Ce que les étudiants ont demandé

Ces leçons proviennent de la construction de pages de révision qui ont été utilisées pour des examens réels :

• Les explications abstraites n'ont pas été comprises. Les étudiants ont d'abord demandé des nombres concrets (« lancez une pièce 10 fois… »), puis la formule, avec les dérivations repliées et étiquetées comme non exigibles à l'examen.
• Étudier plusieurs cours avant de s'entraîner était épuisant. C'est pourquoi chaque section se termine par sa propre boîte d'exercices.
• La sensibilité au format était exaspérante, comme être marqué faux pour 1/2 au lieu de 0.5. Le moteur compare les réponses numériques par valeur ; listez les variantes textuelles dans accept.
• Les étudiants apprennent rapidement les schémas de réponses. La bonne réponse était généralement l'option la plus longue, chaque sélection multiple avait 3 réponses, et la bonne réponse était toujours B. La construction audite les deux premiers ; le moteur mélange l'ordre d'affichage.
• Un examen blanc qui réutilisait des questions d'entraînement mesurait la mémoire, pas la compréhension. C'est pourquoi le pool de l'examen blanc est séparé.
• Les étudiants voulaient pouvoir sélectionner le texte des options pour le copier, et un minuteur qui soumet automatiquement lorsque le temps est écoulé.