Écrire des chapitres pour le site d'un cours qui expliquent le pourquoi avant la formule

## Savoir où placer les pages du cours et leurs traductions Le projet est un site de documentation statique construit à partir des fichiers source du dépôt. Gardez l'arborescence prévisible, afin qu'un contributeur puisse deviner où se trouve chaque chose : - `docs/` — le contenu du cours qui devient les pages publiées. - Le répertoire de configuration du site à l'intérieur de l'arborescence de contenu — configuration et surcharges de thème pour le générateur de site statique. - `docs/public/` — les ressources statiques copiées telles quelles dans le site final. - Un répertoire par langue supplémentaire à l'intérieur de l'arborescence de contenu — des arborescences de traduction qui reflètent la structure de la langue principale. Des pages d'ébauche sont des substituts acceptables dans une arborescence de traduction. - `code/` — des expériences exécutables alignées chapitre par chapitre avec le texte. - `scripts/` — les scripts de maintenance du dépôt, comme la génération du plan de site, la vérification et l'optimisation des ressources. - Le répertoire du workflow d'intégration continue — le pipeline qui construit et déploie le site. Tout nouveau matériel va sous le répertoire de contenu. Les entrées de navigation et de barre latérale sont déclarées dans le fichier de configuration du site, jamais déduites du seul emplacement des fichiers. ## Afficher et vérifier le site en local avec les commandes du projet Travaillez en passant par les points d'entrée de scripts propres au projet plutôt qu'en appelant directement les outils sous-jacents, afin que tout le monde exécute le même pipeline. Un site de documentation de cette forme en expose un petit ensemble fixe : - `npm install` — installer les dépendances. - `npm run dev` — serveur de développement avec optimisation des ressources. - `npm run dev:fast` — serveur de développement qui saute l'optimisation des ressources, pour un démarrage beaucoup plus rapide. - `npm run build` — produire la sortie publiable. - `npm run preview` — servir la sortie construite exactement telle qu'elle sera publiée. - `npm run verify` — contrôles de cohérence à l'échelle du dépôt. - `npm run assets:optimize` — compresser et convertir les images. Utilisez la variante rapide de développement pendant que vous éditez le texte, là où l'optimisation des images ne change rien à ce que vous regardez. Utilisez `build` suivi de `preview` lorsque vous avez besoin de voir la sortie exactement telle qu'elle sera publiée. `verify` est la barrière décrite dans la partie suivante, et `assets:optimize` s'exécute après l'ajout d'images afin que de gros originaux n'atteignent jamais le site publié. ## Mettre à jour le menu de chaque langue et vérifier avant de publier - Gardez chaque modification limitée à la tâche en cours. Ne réécrivez pas des documents ou des configurations sans rapport pendant que vous les traversez. - Préférez ajouter du nouveau matériel de cours sous le répertoire de contenu plutôt que restructurer du matériel qui existe déjà. - Enregistrez les nouvelles pages dans la configuration de navigation et de barre latérale au moment où vous les ajoutez. - Quand une page est ajoutée, déplacée ou renommée, mettez à jour la barre latérale de chaque arborescence de langue qui la reflète, pas seulement celle de la langue principale. Une arborescence de traduction laissée en arrière produit une entrée morte ou une page manquante. - Exécutez la commande de vérification avant de pousser dès que la configuration, le thème ou les scripts de construction ont été touchés. Pousser publie le site : une construction non vérifiée le casse donc en public. ## Créer les schémas avec formules en LaTeX et les convertir en SVG Les figures de style académique avec une véritable composition mathématique sont écrites en tant que source, non dessinées à la main : 1. Écrivez le schéma comme un document autonome dans un langage de schémas vectoriels — par exemple un document LaTeX autonome utilisant un paquet de type TikZ. Copiez le style d'une figure existante du dépôt au lieu d'en inventer un nouveau. 2. Compilez la source avec un moteur LaTeX qui prend en charge les polices que vous utilisez, puis convertissez le PDF obtenu en SVG avec un convertisseur PDF vers SVG. Les deux étapes sont des outils en ligne de commande, de sorte que n'importe quelle figure peut être reconstruite à partir de sa source à tout moment. 3. Conservez à la fois le fichier source et le SVG généré dans le même répertoire `images/`, à côté du chapitre qui les utilise, afin que la figure reste reproductible. 4. Référencez le SVG généré depuis la page markdown par un chemin relatif. Tenez un seul style visuel sur toutes les figures : des boîtes à coins arrondis avec un remplissage très clair et un contour gris foncé, un seul style de pointe de flèche, une police de corps assortie au texte, et des délimiteurs mathématiques en ligne pour les symboles. ## Écrire d'une voix de cours patiente, pas sur un ton de bavardage - Écrivez les chapitres comme du matériel de tutoriel et de cours magistral, non comme des notes de référence laconiques. - Tenez une voix de cours guidé : conversationnelle, patiente et guidée par les problèmes. Les tournures qui tendent au lecteur le pas suivant — « Commençons par l'intuition », « Regardons cela sous un autre angle », « Ce que cette étape signifie, c'est… », « Le véritable problème est… » — sont bienvenues, tandis que le ton reste sérieux et précis. - Ne glissez pas vers un phrasé bavard, de type assistant, ou relevant du langage informel d'internet. Le registre visé est celui d'un chapitre de manuel soigné. - Rythmez les paragraphes pour qu'ils puissent être lus à voix haute ou travaillés seul. Si un paragraphe ne peut pas être suivi à la vitesse de lecture, coupez-le. ## Expliquer tout le raisonnement sans phrases de remplissage Profondeur et économie vont ensemble : expliquez toute la chaîne de raisonnement, et ne dépensez aucun mot sur ce qui est hors de cette chaîne. - Expliquez progressivement — l'intuition d'abord, puis la définition formelle, puis le code ou la pratique. - Donnez le contexte et la raison pour laquelle une étape est nécessaire. Ne comprimez pas un chapitre en une simple liste de résultats. - Supprimez le remplissage d'annonce. Une phrase qui annonce une explication au lieu de la donner (« un exemple rendra ceci plus intuitif ») est supprimée, et l'exemple ou la formule est présenté directement. - Dites chaque chose une seule fois. Ne redites pas le même point avec d'autres mots. - Remplacez les qualificatifs vagues par des énoncés causals précis. Les substituts métaphoriques (« ceci est à peu près équivalent à… ») et les connecteurs d'atténuation n'ont leur place que dans un premier jet. - Évitez les formules de synthèse en forme de slogan qui compriment un mécanisme en une chaîne accrocheuse. Énoncez plutôt le mécanisme concret. - Évitez les listes d'erreurs parallèles au son mécanique (« la requête était trop large, pas de comparaison de prix, mauvais niveau de stock, mauvais paramètre »). Décrivez le processus, et montrez comment un état erroné apparu tôt se propage dans les actions ultérieures. - Évitez le motif de contraste « pas A, mais B » ; il se lit comme indirect. Énoncez l'affirmation positive, puis expliquez pourquoi elle tient. ## Ordonner les idées pour que chaque nouvelle étape arrive avec sa raison - Suivez la ligne causale. Ne tournez pas autour du même point en le résumant, en le redisant, puis en le contrastant. Écrivez dans l'ordre où l'idée change réellement : une nouvelle capacité ou un nouveau cadre apparaît, cela change l'objet d'entraînement ou le problème, et cela rend une nouvelle formulation possible ou inévitable. - Quand vous ouvrez un nouveau concept, préférez la forme « maintenant que X existe, le système fait Y, donc Z devient possible (ou nécessaire) ». - Ouvrez une section en la reliant à ce que le lecteur connaît déjà, puis nommez le nouveau problème que cette section résout. - Ne renvoyez pas à des chapitres antérieurs à moins que ce renvoi soit nécessaire pour la phrase qui suit immédiatement. - Donnez une transition à chaque étape conceptuelle. Ne sautez jamais directement d'une définition à une formule, un terme, un algorithme ou une conclusion ; dites pourquoi l'idée suivante est nécessaire avant de l'introduire. - N'écrivez pas de pages de style encyclopédique qui ne font que lister des définitions. Une définition arrive après sa motivation et elle est suivie d'une interprétation. - Laissez les paragraphes aller de la question à la réponse. Une section bien construite suit d'ordinaire le rythme : exemple familier → tension ou confusion → outil formel → exemple traité → enseignement à retenir. ## Montrer un exemple familier avant la formule et expliquer chaque symbole - Avant d'introduire une formule ou un algorithme, énoncez le problème qu'il résout ; montrez la notation seulement ensuite. - Gardez une formule à côté de son sens : expliquez chaque symbole important, puis redites la formule entière en langage courant. - Cherchez une scène concrète avant une abstraction. De petits dispositifs familiers — une tâche de contrôle d'équilibrage d'une tige, un bandit manchot à plusieurs bras, la génération de texte, une tâche de jeu, un choix de la vie quotidienne — devraient rendre un concept nécessaire avant qu'il soit nommé. - Incluez de petites dérivations au lieu d'affirmer des résultats, et gardez le texte tourné vers l'apprenant d'un bout à l'autre. - Écrivez les termes techniques dans la langue principale du texte chaque fois qu'un équivalent établi existe, plutôt que de laisser le mot anglais emprunté non traduit. Ne conservez un terme anglais que lorsqu'il s'agit d'un acronyme standard ou lorsque le titre du chapitre l'exige, et expliquez-le à sa première apparition. - Utilisez un seul mot fixe par concept sur tout le cours. Un synonyme qui dérive d'un chapitre à l'autre se lit, pour un apprenant, comme un second concept. ## Écrire des sections courtes avec titres et commencer chaque commit par feat:, fix:, etc. - Utilisez des sections courtes avec des titres explicites plutôt que de longs blocs de texte non divisés. - Utilisez le gras avec parcimonie, pour marquer un pivot conceptuel — jamais comme décoration. - Utilisez le kebab-case pour les chemins sous le répertoire de contenu. - Préférez les routes fondées sur un répertoire contenant un `index.md`, afin qu'un sujet puisse grandir en plusieurs pages sans changer son URL. - Utilisez les Conventional Commits pour chaque modification : `feat:`, `fix:`, `docs:`, `chore:`, et ainsi de suite.