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

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.