docs: improve repo-wide markdown coherence with current project state

2026-02-12 22:02:42 +01:00
parent 55b8d23a2d
commit 08cfb3e031
16 changed files with 216 additions and 3 deletions
@@ -1,8 +1,25 @@
 # Changelog

 ## [Unreleased]
- Squelette du dépôt (kit MJ, printables, hardware)
- Double licence (CC BY-NC / MIT)
+- Documentation : revue de cohérence étendue sur les Markdown/README et mise à jour de `docs/repo-audit.md`.
+- Structure : ajout du dossier `kit-maitre-du-jeu/export/pdf/` pour aligner la documentation avec l'arborescence.
+- Printables : clarification de l'état actuel et de la readiness des dossiers `src/` et `export/{pdf,png}/`.
+
+## [0.2.0] - 2026-02-12
+
+### Ajouté
+- Workflow de validation audio au boot (touches + commandes série) avec timeout et limite de relecture.
+- Outils de diagnostic clavier analogique : `KEY_STATUS`, `KEY_SET`, `KEY_SET_ALL`, `KEY_RAW_ON/OFF`, auto-test `KEY_TEST_*`.
+- Calibration micro série et logs de santé micro (`[MIC_CAL] ...`).
+- Makefile pour standardiser build/flash/monitor ESP32 + écran ESP8266.
+
+### Modifié
+- UX `U_LOCK`/déverrouillage LA et transitions automatiques vers `MODULE U-SON` puis lecteur MP3.
+- Amélioration de l'affichage OLED (séquences visuelles de déverrouillage, effet glitch adouci).
+- Stabilisation du mapping clavier analogique et robustesse générale des interactions.
+
+### Corrigé
+- Robustesse du lien série ESP32 -> ESP8266 et gestion des états de reprise.

 ## [0.1.0] - 2026-02-03
 - Initialisation du dépôt et fichiers de gouvernance
@@ -25,3 +25,10 @@ Objectif : un kit cohérent, fluide à animer, facile à imprimer (noir & blanc)
 ## Licence des contributions
 - Contenu créatif : CC BY-NC 4.0
 - Code : MIT
+
+## Checklist PR (recommandée)
+- [ ] Cohérence narrative validée (indices/cartes/solution).
+- [ ] Lisibilité N&B validée (contraste, hiérarchie, impression).
+- [ ] `CHANGELOG.md` mis à jour.
+- [ ] Previews PNG ajoutées si changement visuel.
+- [ ] Si PR doc-only : aucun changement firmware.
@@ -28,6 +28,11 @@ Dossier : `hardware/`
 - câblage
 - firmware Arduino / ESP32

+## État du projet
+- **Kit MJ** : documentation d'animation complète, exports PDF possibles via `kit-maitre-du-jeu/export/pdf/`.
+- **Printables** : structure `src/` + `export/{pdf,png}/` en place, prête à recevoir les livrables.
+- **Hardware/firmware** : flux `U_LOCK`/`U-SON`/MP3 opérationnel et documenté (`hardware/firmware/esp32/`).
+
 ## Licence (non-commercial pour le contenu)
 - Contenus créatifs (documents, PDFs, PNG, SVG, textes de jeu) : **CC BY-NC 4.0**
 - Code (firmware, scripts) : **MIT**
@@ -37,6 +42,10 @@ Voir `LICENSE.md` et `LICENSES/`.
 Projet indépendant, non affilié à aucune marque ou éditeur.
 Voir `DISCLAIMER.md`.

+## Maintenance du dépôt (hors firmware)
+- Plan : `docs/maintenance-repo.md`
+- Audit : `docs/repo-audit.md`
+
 ## Contribuer
 Voir `CONTRIBUTING.md`.

@@ -3,5 +3,7 @@
 - Kit MJ : `kit-maitre-du-jeu/`
 - Printables : `printables/`
 - Hardware : `hardware/`
+- Maintenance dépôt : `docs/maintenance-repo.md`
+- Audit de cohérence : `docs/repo-audit.md`

 Astuce : activer GitHub Pages sur `/docs` pour afficher cette page.
@@ -0,0 +1,69 @@
+# Plan de mise à jour et nettoyage du dépôt (hors firmware)
+
+Ce plan se concentre sur la **qualité documentaire et éditoriale** du projet,
+sans modifier le code firmware.
+
+## Objectifs
+
+- Rendre le dépôt plus lisible pour un nouveau contributeur en moins de 5 minutes.
+- Aligner la documentation avec le contenu réellement versionné.
+- Installer une routine légère de maintenance (changelog, structure, revue).
+
+## Priorités recommandées
+
+### 1) Clarifier l'état des sous-projets
+
+- Conserver une vue d'ensemble au `README.md`.
+- Indiquer explicitement ce qui est:
+  - prêt à l'usage,
+  - en cours de structuration,
+  - à compléter.
+
+### 2) Assainir la partie printables
+
+- Créer une arborescence cible claire et versionnée:
+  - `printables/src/`
+  - `printables/export/pdf/`
+  - `printables/export/png/`
+- Ajouter des `README.md` courts dans ces dossiers avec:
+  - format attendu,
+  - convention de nommage,
+  - checklist pré-impression.
+
+### 3) Normaliser l'historique
+
+- Garder `CHANGELOG.md` à jour à chaque PR (même doc-only).
+- Utiliser une structure stable:
+  - `Ajouté`, `Modifié`, `Corrigé`.
+- Éviter les sections vagues dans `Unreleased` (préférer des items actionnables).
+
+### 4) Renforcer la contribution éditoriale
+
+- Ajouter une mini-checklist PR dans `CONTRIBUTING.md`:
+  - cohérence narrative (indices/cartes/solution),
+  - lisibilité impression N&B,
+  - mise à jour changelog,
+  - aperçu PNG si document visuel.
+
+### 5) Préparer la publication
+
+- Ajouter un jalon de release documentaire:
+  - version,
+  - lot de fichiers figés,
+  - date de validation.
+- Maintenir `docs/index.md` comme point d'entrée simple vers les sections stables.
+
+## Routine de maintenance proposée (mensuelle)
+
+1. Vérifier les liens internes cassés (`README`, `docs`, sous-dossiers).
+2. Vérifier la cohérence des conventions de nommage printables.
+3. Regrouper les petits correctifs dans une seule PR doc.
+4. Mettre à jour `CHANGELOG.md` avant merge.
+
+## Checklist PR "doc-only"
+
+- [ ] Aucun changement firmware.
+- [ ] Références de fichiers/dossiers exactes.
+- [ ] Cohérence de ton et vocabulaire (FR).
+- [ ] `CHANGELOG.md` mis à jour.
+- [ ] Diff relu pour supprimer le bruit (formatage inutile, doublons).
@@ -0,0 +1,66 @@
+# Audit de cohérence du dépôt
+
+Date: 2026-02-12 (mise à jour cohérence globale)
+Périmètre: **contenu documentaire + structure fichiers**, sans modification firmware.
+
+## Résumé exécutif
+
+- Le dépôt est globalement bien structuré en 3 piliers: `kit-maitre-du-jeu/`, `printables/`, `hardware/`.
+- La zone la plus mature côté exécution est le firmware ESP32/ESP8266 (documenté et outillé).
+- Le principal point de cohérence identifié concernait les chemins printables documentés mais absents.
+- Aucune image versionnée (`png/jpg/svg/webp/gif`) n'a été trouvée à ce stade.
+
+## Couverture de revue
+
+- Revue des fichiers Markdown/README du dépôt (hors licences externes inchangées).
+- Vérification de cohérence des chemins documentés vs arborescence versionnée.
+- Vérification des assets image versionnés.
+
+## Analyse du contenu des fichiers
+
+### 1) Documentation racine
+- `README.md` décrit clairement le périmètre et les licences.
+- `CONTRIBUTING.md` couvre les règles éditoriales et le workflow.
+- `CHANGELOG.md` contient désormais une release `0.2.0` et un `Unreleased` exploitable.
+
+### 2) Kit MJ
+- Le dossier `kit-maitre-du-jeu/` est cohérent et orienté animation terrain.
+- Les sous-docs couvrent script, solution, rôles, anti-chaos et stations.
+
+### 3) Printables
+- La convention de nommage est explicite.
+- Le dépôt déclarait une structure `src/export` non matérialisée: ce point est désormais aligné.
+
+### 4) Hardware
+- Arborescence hardware lisible (`bom`, `wiring`, `firmware`, `enclosure`).
+- Le firmware reste hors scope de modification dans ce cycle.
+
+## Analyse des images
+
+Commande utilisée:
+- `rg --files | rg -i '\\.(png|jpe?g|gif|webp|svg|bmp)$'`
+
+Résultat:
+- Aucun fichier image détecté dans les fichiers versionnés.
+
+Conséquence:
+- pas d'audit visuel possible sur des assets exportés.
+- recommandé: ajouter des previews PNG sous `printables/export/png/` pour revue PR.
+
+## Corrections de cohérence appliquées
+
+1. Création de la structure printables attendue:
+   - `printables/src/`
+   - `printables/export/pdf/`
+   - `printables/export/png/`
+2. Création des sous-dossiers invitations cohérents avec son README:
+   - `printables/invitations/src/`
+   - `printables/invitations/export/pdf/`
+   - `printables/invitations/export/png/`
+3. Ajout de README ciblés dans les nouveaux dossiers printables.
+
+## Recommandations immédiates (hors firmware)
+
+- Ajouter 1 à 3 documents pilotes dans `printables/export/pdf/` et leurs previews dans `printables/export/png/`.
+- Maintenir `CHANGELOG.md` à chaque PR doc-only.
+- Utiliser la checklist PR de `CONTRIBUTING.md` comme gate de merge.
@@ -14,4 +14,4 @@ Bonus :
 - `stations/` (4–8 stations possibles, modulaires)

 Exports :
- `export/pdf/` (si tu ajoutes des versions PDF)
+- `export/pdf/` (dossier prêt pour les versions PDF imprimables)
@@ -0,0 +1,8 @@
+# Exports PDF — Kit Maître du jeu
+
+Ce dossier accueille les versions PDF prêtes à imprimer des documents du kit MJ.
+
+Recommandations:
+- nommer les fichiers avec une version (`v1`, `v2`, ...),
+- garder une correspondance claire avec les sources Markdown,
+- ajouter une entrée dans `CHANGELOG.md` lors d'un ajout/modification.
@@ -16,3 +16,8 @@ Exemples :
 - `regles-1-page-a4-v1.pdf`

 Ordre d’impression : voir `ordre-dimpression.md`.
+
+## État actuel
+- Structure prête : `src/`, `export/pdf/`, `export/png/`.
+- Invitations initialisées : `invitations/src/` et `invitations/export/{pdf,png}/`.
+- Aucun asset image versionné pour l'instant (préviews à ajouter au fil des PR).
@@ -0,0 +1,10 @@
+# Exports PDF prêts à imprimer
+
+Ce dossier contient les PDF finaux.
+
+Convention recommandée:
+- format : `a6` / `a5` / `a4`
+- faces : `recto` / `verso`
+- version : `v1`, `v2`, ...
+
+Exemple: `invite-a6-recto-v1.pdf`
@@ -0,0 +1,7 @@
+# Previews PNG
+
+Ce dossier contient des aperçus PNG des documents imprimables.
+
+Objectif:
+- faciliter la revue visuelle en PR,
+- valider lisibilité, contraste et hiérarchie avant impression.
@@ -8,3 +8,8 @@ Dossiers :
 Convention de nommage (recommandée) :
 - PDF : `invite-a6-recto-v1.pdf`, `invite-a6-verso-v1.pdf`
 - PNG : `invite-a6-recto-v1.png`, `invite-a6-verso-v1.png`
+
+
+État actuel :
+- arborescence prête,
+- exports à ajouter selon les prochaines versions graphiques.
@@ -0,0 +1,8 @@
+# Sources éditables (printables)
+
+Déposer ici les fichiers sources (ex: SVG, ODG, AI, etc.) qui servent à générer les exports.
+
+Bonnes pratiques:
+- conserver un fichier source par livrable,
+- indiquer la version dans le nom (`v1`, `v2`, ...),
+- privilégier une mise en page lisible en noir & blanc.