11 KiB
Documentation rules
Scope
Ce document définit les règles communes de documentation gouvernée par PGR : rôle des documents, taxonomie, révision interne des fichiers, distinction entre documents vivants et snapshots historiques, conservation et suppression.
La documentation doit réduire le coût de compréhension et de reprise du projet. Elle MUST NOT devenir une duplication systématique du code, des manifests ou de l'historique de release.
Responsabilités documentaires
Chaque type de document doit conserver une responsabilité claire.
Root README.md
Le README.md racine présente le projet et fournit l'onboarding et la navigation de premier niveau.
Il SHOULD rester concis et pointer vers les documents spécialisés plutôt que recopier leurs contenus.
docs/000-README.md
docs/000-README.md est l'index principal de la collection documentaire lorsqu'un projet possède une documentation structurée sous docs/.
Il décrit l'organisation documentaire et les points d'entrée utiles ; il MUST NOT devenir un second README produit ou un journal de release.
Un sous-ensemble documentaire MAY utiliser son propre 000-README.md lorsqu'un index local améliore réellement la navigation.
README local
Un README.md local à un composant, module ou répertoire décrit la responsabilité et les informations d'entrée propres à ce composant.
Il SHOULD NOT recopier la documentation globale qui reste mieux possédée ailleurs.
USAGE.md
Lorsqu'il existe, USAGE.md est un guide d'utilisation durable et autant que possible indépendant d'une version précise.
Il peut contenir exemples, scénarios, contraintes opérationnelles et contrats d'utilisation. Il MUST NOT servir de changelog, de preuve de validation, de résumé de prerelease ou de history de tranche.
RULES.md
RULES.md est le point d'entrée normatif du projet. Il présente la hiérarchie et les règles fondamentales et renvoie vers les familles détaillées lorsque celles-ci existent.
Il SHOULD NOT devenir un fichier monolithique contenant toutes les règles spécialisées.
ROADMAP.md
ROADMAP.md décrit la trajectoire macro du projet : objectifs de versions, grandes étapes et ordre fonctionnel attendu.
Il MUST NOT devenir un journal des prereleases ou recopier les histories de tranche.
Lorsqu'un projet utilise des statuts de roadmap, la convention PGR est :
( ) planned
(x) completed
(d) deferred
(c) cancelled
Une autre convention MAY être adoptée par un projet si elle est explicitement définie et cohérente.
CHANGELOG.md
CHANGELOG.md décrit les changements utiles aux utilisateurs ou intégrateurs d'une release.
Par défaut, les tranches alpha et beta ne doivent pas créer de bruit de changelog simplement parce qu'elles existent. Une RC MAY préparer l'entrée de release et la stable la finalise.
Un projet MAY documenter des prereleases publiquement distribuées lorsque cela apporte une information réelle aux consommateurs.
Objectifs
Un document sous docs/objectives/ décrit la mission durable, les objectifs, contraintes et non-objectifs du projet.
Il MUST NOT être remplacé par ROADMAP.md : les objectifs expliquent pourquoi le projet existe et ce qu'il cherche à garantir ; la roadmap décrit comment sa trajectoire est découpée.
Registre local de contrats de fichiers ou familles
Un projet MAY maintenir un registre local lorsque plusieurs fichiers ou familles durables ont des responsabilités, sources de vérité ou règles de modification qui ne sont pas suffisamment évidentes depuis leur nom, leur écosystème ou leurs owners existants.
Ce registre est un outil de désambiguïsation, pas un inventaire exhaustif de l'arborescence. Il MUST NOT être créé uniquement pour recopier les rôles déjà définis par PGR, un manifeste, une toolchain ou une documentation locale plus appropriée. Un petit projet dont les responsabilités sont déjà claires SHOULD ne pas créer ce document.
Chaque entrée utile SHOULD identifier au minimum :
- le fichier, motif de chemin ou famille concernée ;
- sa responsabilité durable ;
- la règle ou le déclencheur pertinent de modification.
Selon le besoin, une entrée MAY aussi préciser une source de vérité, le caractère généré/versionné, un owner local ou une validation associée. Ces champs supplémentaires ne doivent être ajoutés que s'ils réduisent réellement une ambiguïté.
Le nom, l'emplacement et la forme du registre appartiennent au projet destinataire. PGR n'impose ni FILE_CONTRACTS.md, ni une table Markdown, ni un catalogue de chaque fichier. Une liste courte, une table ou une autre forme lisible sont équivalentes si le contrat reste explicite.
Lorsqu'un owner existant possède déjà la règle détaillée, le registre SHOULD le référencer plutôt que dupliquer son contenu. Il est mis à jour lorsque le contrat d'une famille change réellement ; l'ajout d'un fichier conforme à une famille déjà décrite ne force pas une nouvelle entrée.
../templates/004-FILE_FAMILY_CONTRACTS.md fournit un pattern documentaire court pour les projets qui choisissent d'adopter ce registre.
Taxonomie documentaire
La taxonomie doit rester sémantique et proportionnée. Les familles communes comprennent notamment :
docs/rules/
docs/objectives/
docs/ideas/
docs/studies/
docs/architecture/
docs/plans/
docs/validation/
docs/development/
docs/testing/
docs/operations/
docs/reference/
docs/formats/
Ces répertoires ne sont créés que lorsqu'ils possèdent un contenu réel.
Un répertoire générique tel que misc/ SHOULD NOT devenir la destination par défaut des documents dont la responsabilité n'a pas été déterminée.
Une technologie ou un projet MAY introduire des familles supplémentaires lorsqu'elles représentent une responsabilité documentaire stable.
Idées, études et décisions
Une idée est une possibilité non engagée. Elle ne doit pas être présentée comme une décision ou une promesse de roadmap.
Une étude existe lorsqu'un choix réel doit être comparé ou démontré. Elle SHOULD expliciter la question, les contraintes, les options pertinentes, les observations et la décision ou conclusion lorsqu'elle existe.
Si une décision est déjà imposée par une contrainte explicite et qu'aucune alternative réelle n'est ouverte, une étude artificielle SHOULD NOT être créée uniquement pour respecter un processus.
Les décisions durables doivent ensuite être reflétées dans l'architecture, les règles, objectifs ou autres documents vivants qui possèdent réellement ce contrat.
Documents vivants et snapshots historiques
PGR distingue :
living document
→ décrit l'état ou le contrat courant et évolue lorsque cet état change réellement
historical snapshot
→ enregistre un état, une décision ou une preuve à un instant donné
Exemples de documents généralement vivants :
README.md
RULES.md
ROADMAP.md
docs/000-README.md
PROJECT_PROFILE
validation matrix
architecture courante
Exemples de snapshots généralement historiques après livraison/commit :
delta
history
handoff livré
étude conclue conservée comme preuve
release/publish record
Un snapshot historique MUST NOT être réécrit silencieusement pour correspondre à l'état courant. Une correction factuelle importante doit être explicite et préserver la traçabilité utile.
Un document vivant SHOULD être mis à jour lorsqu'un changement rend son contenu réellement obsolète ; il ne doit pas être modifié à chaque tranche uniquement pour créer une trace d'activité.
Header file / version
Pour les formats texte qui acceptent naturellement des commentaires, PGR SHOULD utiliser un header interne de la forme :
file: relative/path
version: N
La syntaxe de commentaire dépend du format. Pour Markdown :
<!-- file: docs/example.md -->
<!-- version: 1 -->
Dans le dépôt PGR, README.md, RULES.md, ROADMAP.md, CHANGELOG.md et les fichiers Markdown gouvernés sous docs/, deltas/, history/ et prompts/ MUST placer ces deux commentaires sur leurs deux premières lignes. Le file MUST être le chemin relatif depuis la racine du dépôt et version MUST être un entier positif sans zéro initial. scripts/audit_markdown_headers.py contrôle mécaniquement ces deux champs pour les chemins explicitement sélectionnés. Ce contrôle ne juge ni le contenu du document, ni si le numéro de révision a réellement été incrémenté lors d'un changement.
file identifie le chemin relatif canonique du fichier.
version est une révision interne du fichier. Elle est indépendante de VERSION, de SemVer produit, des versions de protocole, de schema ou de package.
La révision interne MUST être incrémentée lorsqu'un fichier subit une modification réelle gouvernée ou un déplacement qui modifie son chemin canonique. Elle SHOULD NOT être incrémentée pour une opération de formatage strictement mécanique qui ne modifie aucun contenu gouverné.
Lors d'un déplacement, le header file MUST être mis à jour vers le nouveau chemin.
Les formats stricts ou formats dans lesquels un tel header serait invalide MUST NOT recevoir de champ artificiel uniquement pour satisfaire cette convention. La provenance ou révision est alors portée ailleurs si nécessaire.
Noms et ordre documentaire
Les noms de fichiers doivent refléter leur responsabilité. Les suffixes vagues ou chronologiques tels que new, old, final2 SHOULD NOT être utilisés comme mécanisme de versionnement.
Un préfixe numérique MAY être utilisé pour stabiliser la navigation d'une collection documentaire lorsqu'un ordre est utile. Le numéro organise la lecture ; il ne constitue pas un identifiant normatif de règle.
Conservation, suppression et remplacement
Une documentation historique utile SHOULD être conservée lorsqu'elle explique une décision, une migration ou permet une reprise fiable.
Un document MAY être supprimé lorsqu'il est devenu nuisible, réellement obsolète, redondant ou explicitement superseded. Lorsque la suppression n'est pas évidente, le changement SHOULD identifier la raison et le remplacement éventuel.
PGR MUST NOT imposer la conservation infinie de contenu sans valeur de preuve ou de reprise.
Langues et traductions
Le choix de langue appartient au projet et doit rester cohérent avec ses règles locales.
Pour PGR lui-même, la nomenclature technique, les chemins, identifiants et le code restent en anglais tandis que les explications normatives sont en français.
PGR MUST NOT créer d'arborescence fr/, en/, de/ ou équivalente dans son dépôt principal. Une traduction intégrale éventuelle appartient à un dépôt distinct tel que pgr-en, pgr-de ou pgr-ar.
Documentation proportionnée
Un document SHOULD exister lorsqu'il possède une responsabilité durable, une décision, une preuve ou une information de reprise qui ne serait pas mieux portée ailleurs.
PGR MUST NOT imposer :
- un document vide pour satisfaire une structure théorique ;
- une copie de la même information dans plusieurs fichiers sans propriétaire clair ;
- un document de décision lorsqu'aucune décision n'est réellement ouverte ;
- une mise à jour documentaire purement cérémonielle à chaque tranche.
La documentation est une aide au développement et à la maintenance, pas une fin en soi.