v0.0.2

docs/rules/RULES_DOCUMENTATION.md

@@ -0,0 +1,48 @@
+<!-- file: docs/rules/RULES_DOCUMENTATION.md -->
+<!-- version: 4 -->
+
+# Règles de documentation
+
+## Portée
+
+Les règles `DOC-*` s'appliquent aux documents Markdown internes et à leur organisation.
+
+## Principes
+
+- **DOC-ROOT-001** — `README.md` à la racine décrit KSP, sa finalité, ses principes structurants et les points d'entrée du dépôt ; il ne sert ni de changelog ni de plan détaillé de version.
+- **DOC-ROOT-002** — Le point d'entrée d'un répertoire documentaire utilisant une priorité explicite se nomme `000-README.md`. Le préfixe `000-` garantit qu'il reste en première position dans les listings et arbres de fichiers lorsque le volume documentaire devient important.
+- **DOC-ROOT-003** — Dans un répertoire documentaire où un ordre de lecture, de priorité ou d'affichage est utile, les autres documents prioritaires peuvent être préfixés `001-`, `002-`, etc. Le préfixe numérique n'est pas appliqué mécaniquement à tous les fichiers.
+- **DOC-ROOT-004** — La convention `000-`, `001-`, `002-`, etc. ne s'applique pas aux fichiers situés à la racine du dépôt. `README.md`, `RULES.md`, `ROADMAP.md`, `CHANGELOG.md` et les autres fichiers racine conservent leur nom canonique sans préfixe numérique.
+- **DOC-ROOT-005** — `RULES.md` est le seul index normatif à la racine et renvoie vers les règles détaillées sous `docs/rules/`.
+- **DOC-ROOT-006** — KSP utilisera au plus un `CHANGELOG.md` général à la racine ; aucun changelog spécifique par crate ou module n'est créé par défaut.
+- **DOC-ROOT-007** — `ROADMAP.md` décrit les objectifs et grandes étapes globales par phase/version. Chaque bloc peut comporter un `Status` optionnel et utilise la légende `[ ]` prévu, `[/]` en cours, `[X]` réalisé et validé, `[C]` annulé et `[R]` reporté.
+- **DOC-ROOT-008** — `CHANGELOG.md` contient les releases stables dans un ordre chronologique décroissant. Chaque release est résumée par un ou plusieurs paragraphes ; le changelog général ne recopie pas le détail des deltas.
+
+## Deltas et documents durables
+
+- **DOC-DELTA-001** — Les fichiers `deltas/<X.Y.Z>/<delta-name>.md` sont des journaux de livraison versionnés et commités ; ils ne sont pas placés sous `docs/`.
+- **DOC-DELTA-002** — Aucun second système de fichiers de version n'est créé sous `docs/`.
+- **DOC-DELTA-003** — Les décisions devenues durables sont reportées dans les documents normatifs, architecturaux ou de référence appropriés ; le delta reste une trace historique de la livraison.
+- **DOC-DELTA-004** — Le changelog général, lorsqu'il sera défini et introduit, synthétisera les changements significatifs sans dupliquer chaque détail des deltas.
+
+## Idées à explorer
+
+- **DOC-IDEAS-001** — `docs/IDEAS.md` conserve les idées, pistes, alternatives et questions qui doivent rester visibles sans constituer encore une décision ou un engagement de développement.
+- **DOC-IDEAS-002** — Une idée peut utiliser les statuts `À explorer`, `En exploration`, `Retenue`, `Rejetée`, `Transférée au roadmap` ou `Transférée vers une décision/règle`.
+- **DOC-IDEAS-003** — Lorsqu'une idée devient un engagement, elle est transférée vers le roadmap ou un plan ; lorsqu'elle devient une décision durable, elle est reportée dans le document normatif ou architectural approprié. `IDEAS.md` conserve une trace concise de son issue.
+- **DOC-IDEAS-004** — `IDEAS.md` ne doit pas devenir un second roadmap ni une liste de tâches de développement promises.
+
+## Contenu et exactitude
+
+- **DOC-CONTENT-001** — Une documentation décrit l'état réellement décidé ou validé et distingue explicitement les hypothèses, propositions, TODO et questions ouvertes.
+- **DOC-CONTENT-002** — Une validation non exécutée est identifiée comme telle.
+- **DOC-CONTENT-003** — Une source historique est synthétisée et réévaluée ; elle n'est pas copiée mécaniquement comme documentation KSP active.
+- **DOC-CONTENT-004** — Les exemples de chemins et noms suivent la nomenclature KSP active au moment de l'écriture.
+
+## Documents de crates
+
+- **DOC-CRATE-001** — Il est préférable qu'une crate dispose de `README.md`, `TODO.md` et surtout `USAGE.md`, mais leur présence n'est pas imposée mécaniquement lorsque le fichier n'apporte encore aucune information utile.
+- **DOC-CRATE-002** — `README.md` décrit la responsabilité, le périmètre, les frontières et les principaux points d'entrée d'une crate.
+- **DOC-CRATE-003** — `TODO.md` conserve les tâches, lacunes et vérifications propres à la crate afin d'éviter les oublis ; il ne remplace pas la planification globale ou les deltas.
+- **DOC-CRATE-004** — `USAGE.md` documente l'utilisation concrète de la crate, ses préconditions, ses principaux contrats et des exemples pertinents ; il est particulièrement recommandé dès qu'une crate possède une API consommable.
+- **DOC-CRATE-005** — Aucun `CHANGELOG.md` de crate n'est créé par défaut ; la traçabilité détaillée est assurée par `deltas/` et, lorsqu'il sera défini, par le changelog général.