docs — V32 à V34 au plan : documentation et tutoriels, en trois vagues

[dapiced]

Une route /docs, liée depuis le pied de page à côté de « Comment ça marche », bâtie sur la séparation Diátaxis : tutoriel (apprendre), guide pratique (accomplir), référence (consulter), explication (comprendre). L'échec habituel d'une documentation est de mélanger les quatre sur la même page — un tutoriel qui s'interrompt pour peser une alternative perd exactement le débutant pour qui il a été écrit.

Cinq règles propres à ce projet

Écrites dans le PLAN pour qu'elles ne se perdent pas en cours de rédaction :

1. La doc est testée comme le code. Tout est seedé à 42 : « vous obtiendrez 0,821 d'exactitude » devient une assertion dans e2e/docs.spec.ts, et une page qui dérive casse le build. Une documentation qui ne peut pas mentir, c'est la même promesse que le reste du site.
2. Les captures sont générées par Playwright. Une capture qu'on ne peut pas régénérer n'entre pas.
3. Mieux qu'une capture : un lien qui fait la chose — « essayez-le » ouvre le panneau avec la démo déjà chargée. Ça ne périme jamais.
4. Le Markdown vit dans le dépôt, coquilles prérendues, recherche locale — pas d'Algolia ni de service tiers sur un site qui publie une page /privacy.
5. La doc n'est pas PLAN.md : registre d'ingénierie en anglais d'un côté, pages utilisateur bilingues de l'autre. Deux publics, deux fichiers.

Le découpage

Vague	Contenu	Effort
V32	Charpente (/docs, pipeline Markdown, sommaire, recherche) + un tutoriel complet testé	1 journée
V33	Référence des trois sections + table des refus nommés	1–2 journées de rédaction
V34	Explications, guides pratiques, captures générées, « ce que LabML ne fait pas »	1 journée

La page que personne d'autre n'a : la table des refus — filter-not-numeric, llm-part-missing, too-large, no-webgpu, « aucun des deux n'a compris », « l'intervalle n'est pas concluant » — avec ce qui les déclenche et quoi faire. Refuser proprement est la particularité du projet ; documenter les refus est la page la plus honnête qu'il puisse publier.

Estimation assumée : la charpente tient en une journée, mais documenter vingt-cinq fonctionnalités correctement en deux langues, c'est de la rédaction. Ça ne s'automatise pas sans produire de la bouillie, et trois vagues honnêtes valent mieux qu'une qui accouche de pages creuses.

Ordre : V32 livre un seul tutoriel entièrement fini, parce qu'il sert de gabarit — ton, longueur, façon de citer les chiffres. Écrire la référence avant d'avoir fixé ce gabarit, c'est se condamner à tout réécrire. C'est noté dans le paragraphe d'ordonnancement.

Documentation seule — aucun code touché.

---

Generated by Claude Code

[Copilot]

🟢 Approval recommended

The change is limited to roadmap/documentation planning text in PLAN.md and does not introduce code or behavioral risk.

Pull request overview

This PR updates the project roadmap in PLAN.md to define a three-wave documentation initiative (V32–V34), introducing a /docs route concept and organizing future docs work around the Diátaxis framework (tutorial / how-to / reference / explanation), including principles like testable docs and generated screenshots.

Changes:

• Adds roadmap entries for V32–V34 detailing the docs architecture, a first fully tested tutorial, a full reference, and a “table of named refusals”.
• Clarifies the intended ordering: ship one complete tutorial before writing the reference to establish a consistent template/tone.
• Records project-specific documentation rules (tested assertions, Playwright screenshots, repo-hosted Markdown, deep-links over screenshots, separation from PLAN.md).

File summaries

File	Description
PLAN.md	Adds V32–V34 roadmap items and updates the “Ordering” rationale for the documentation waves.

Review details

• Files reviewed: 1/1 changed files
• Comments generated: 0
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.