khadhroony-solana-project/docs/rules/RULES_DOCUMENTATION.md

<!-- file: docs/rules/RULES_DOCUMENTATION.md -->
<!-- version: 7 -->

# 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.

## Format des tableaux Markdown

- **DOC-TABLE-001** — Un tableau Markdown KSP utilise `|` uniquement comme séparateur structurel de colonnes. Un caractère `|` littéral, y compris sous forme échappée `\|`, est interdit dans le contenu d’une cellule ; reformuler le contenu, utiliser `/`, `et`, une liste ou un bloc de code hors tableau.
- **DOC-TABLE-002** — Toutes les lignes d’un même tableau ont leurs séparateurs verticaux aux mêmes positions. La largeur de chaque colonne est déterminée par le contenu le plus large de cette colonne, en comptant l’en-tête et les lignes de données.
- **DOC-TABLE-003** — L’alignement source des cellules suit la ligne séparatrice. Une colonne `|---|` ou `|:---|` est alignée à gauche : chaque contenu possède exactement un espace gauche et uniquement le padding droit nécessaire. Une colonne `|---:|` est alignée à droite : chaque contenu possède exactement un espace droit et uniquement le padding gauche nécessaire. Une colonne `|:---:|` est centrée : les paddings gauche et droit diffèrent d’au plus un espace. Chaque cellule conserve au minimum un espace de chaque côté du contenu.
- **DOC-TABLE-004** — La cellule séparatrice en tirets occupe exactement toute la largeur de la colonne, sans espace entre ses marqueurs et les séparateurs `|`. Elle contient au moins trois tirets ; `:---` sélectionne l’alignement gauche explicite, `---:` l’alignement droit et `:---:` le centrage. Le résultat attendu est équivalent au reformatage de tableau produit par RustRover, mais la règle structurelle KSP prime sur l’éditeur utilisé.
- **DOC-TABLE-005** — Lorsqu’une modification touche une ligne d’un tableau, le tableau entier est réaligné avant livraison. `python3 scripts/audit_markdown_tables.py <fichiers-markdown-modifiés>` est le canari mécanique recommandé pour les fichiers concernés ; il doit reconnaître et rejeter une ligne séparatrice Markdown plausible même lorsque des espaces erronés l’empêchent de respecter `DOC-TABLE-004`. Les blocs de code fenced ne sont pas interprétés comme des tableaux.
- **DOC-TABLE-006** — L’immuabilité des deltas déjà publiés prime sur un reformatage rétrospectif : un ancien fichier `deltas/` n’est jamais réécrit uniquement pour satisfaire une règle de présentation introduite ultérieurement. Tout nouveau delta et tout autre tableau modifiable créé ou touché doivent en revanche respecter immédiatement `DOC-TABLE-001` à `DOC-TABLE-005`.

## Espacement vertical Markdown

- **DOC-BLANK-001** — Hors bloc de code fenced, un document Markdown KSP ne contient jamais plus d’une ligne vide consécutive. Une ligne composée uniquement d’espaces ou de tabulations est considérée comme vide.
- **DOC-BLANK-002** — `python3 scripts/audit_markdown_tables.py <fichiers-ou-répertoires>` contrôle aussi les lignes vides multiples. Lors d’un parcours récursif, les répertoires générés ou tiers tels que `node_modules`, `dist`, `target`, `.git`, `.idea`, `.venv` et `__pycache__` sont exclus afin que le résultat porte uniquement sur les Markdown KSP-owned. Les blocs de code fenced conservent librement leur espacement interne.
- **DOC-BLANK-003** — Les deltas déjà publiés restent immuables et ne sont jamais réécrits uniquement pour satisfaire `DOC-BLANK-001`. Les audits de release portent sur le répertoire de delta actif et sur les autres Markdown modifiables ; un audit historique explicite peut donc signaler des écarts hérités sans autoriser leur correction rétroactive.

## 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.