Documentation Standards¶

Status: NORMATIVE / GOVERNANCE

Objet¶

Ce document définit les standards officiels de la documentation CMonChoix Platform.

La documentation doit permettre de distinguer sans ambiguïté la cible architecturale, l'état réellement actif et l'historique du projet.

Source officielle¶

docs/ est la source documentaire officielle de la Platform.

Les README locaux sous src/, plugins/, operations/ ou d'autres dossiers peuvent expliquer leur périmètre local, mais ils ne doivent pas créer une architecture officielle concurrente.

En cas de contradiction :

Constitution et contrats normatifs ;
architecture normative ;
documentation CURRENT du composant ;
procédures d'exploitation CURRENT ;
notes de migration ;
documents HISTORICAL.

Statuts documentaires¶

Utiliser un statut explicite en tête des documents structurants.

`NORMATIVE` / `CONTRACT`¶

Règle ou frontière durable que les évolutions doivent respecter.

`CURRENT`¶

Décrit un comportement réellement actif, observé ou certifié dans la révision courante.

Une page CURRENT doit être mise à jour lorsque le comportement change.

`TARGET`¶

Décrit la destination recherchée. Une page TARGET ne prouve pas que l'implémentation existe déjà.

`TRANSITIONAL`¶

Décrit un mécanisme temporaire conservé pour compatibilité pendant une migration.

Un élément TRANSITIONAL doit avoir une cible et idéalement des critères de sortie.

`HISTORICAL`¶

Conserve le contexte d'une ancienne architecture, mission, certification ou décision.

Il ne doit pas guider une nouvelle implémentation en cas de contradiction avec CURRENT/NORMATIVE.

`DEPRECATED`¶

Composant, chemin ou document qui peut encore exister mais ne doit plus recevoir de nouvelle responsabilité.

`DRAFT`¶

Proposition non normative. Elle ne doit pas être utilisée comme preuve de comportement CURRENT ou comme contrat certifié.

CURRENT vs TARGET¶

Ne jamais écrire une phrase ambiguë qui mélange l'existant et la destination.

Préférer :

CURRENT
Le worker est encore lancé via WP-CLI.

TARGET
Le worker Platform fonctionne sans charger WordPress.

plutôt que :

Le worker est indépendant de WordPress.

si ce n'est pas encore vrai dans le Runtime.

Dette et exceptions¶

Lorsqu'un état CURRENT viole la cible normative :

ne pas modifier la norme pour faire correspondre la dette ;
marquer l'état comme TRANSITIONAL/CURRENT ;
enregistrer la dette dans docs/engineering/technical-debt.md si elle est significative ;
documenter les critères de sortie.

Documentation locale du plugin¶

Un document sous plugins/ccx-feeds-industrial/ doit être considéré comme local au plugin.

Il ne doit pas :

se proclamer racine documentaire officielle de la Platform ;
redéfinir les invariants ;
déclarer le plugin propriétaire du Core métier ;
présenter une ancienne roadmap comme cible CURRENT.

Les documents historiques conservés dans le plugin doivent renvoyer vers docs/.

Exigences de contenu¶

Un document opérationnel ou architectural important doit permettre de répondre lorsque pertinent :

quel est son statut ?
quel est son scope ?
qui possède la responsabilité ?
quelle est la source de vérité ?
quelles dépendances sont autorisées/interdites ?
quel est le comportement d'échec ?
comment vérifier le comportement ?
quelle est la voie de rollback/recovery ?
quelles dettes ou limites restent ouvertes ?

Documentation et code¶

La documentation ne remplace pas les tests.

Une affirmation de comportement Runtime doit être corroborée par les preuves adaptées : code actif, tests, guards, fixtures, métriques ou exécution contrôlée.

Une certification purement documentaire ne suffit pas pour déclarer qu'une frontière technique fonctionne réellement.

Liens et duplication¶

une page canonique par sujet ;
les pages secondaires renvoient vers la page canonique au lieu de recopier tout le contrat ;
éviter plusieurs roadmaps concurrentes ;
éviter les listes statiques de détails Runtime susceptibles de dériver lorsqu'une source CURRENT existe ailleurs ;
les rapports historiques restent datés et explicitement HISTORICAL.

Secrets et données sensibles¶

Interdits dans la documentation :

credentials ;
tokens ;
secrets HMAC ;
URLs privées contenant des secrets ;
données personnelles non nécessaires ;
dumps de production sensibles.

Utiliser des noms de variables/configuration sans leurs valeurs.

Validation¶

La documentation publiée doit passer les contrôles documentaires du dépôt, notamment :

make docs-check

ou l'entrée MkDocs stricte équivalente documentée par la révision.

Review checklist¶

[ ] statut explicite et cohérent
[ ] CURRENT et TARGET non mélangés
[ ] aucune architecture concurrente créée
[ ] responsabilité/source de vérité correcte
[ ] liens vers documents normatifs corrects
[ ] dette enregistrée si nécessaire
[ ] aucun secret
[ ] commandes vérifiées contre la révision
[ ] build documentaire validé