Structure de documentation
La documentation a un seul rôle : faciliter la prochaine bonne décision.
Utilisez la section qui correspond au type de décision documentée :
| Section | Possède |
|---|---|
| Identité | Repères de reconnaissance : logo, voix, kit média et actifs publics de marque |
| Fondations | Primitives visuelles : couleur, typographie, jetons, mise en page, accessibilité, actifs |
| Gouvernance du site | Règles durables : responsabilité, URL, nommage, contenu, confidentialité, qualité, réutilisation |
| Implémentation du site | Mécanique : Hugo, Workers, composants, motifs, shortcodes, outillage, sorties générées |
| ADR du dépôt | Historique interne des décisions, compromis, conséquences et suivis futurs |
Règle#
Placez la règle là où le lecteur doit l’appliquer. Gardez le raisonnement historique dans un ADR lorsque la décision change la structure, le modèle de responsabilité, le modèle de qualité ou la frontière technique des sites.
Frontières#
- Un actif de marque appartient à Identité.
- Une primitive visuelle appartient aux Fondations.
- Une règle qui devrait survivre à une réécriture de gabarit appartient à la Gouvernance du site.
- Un gabarit, un partiel, un shortcode, un script, un comportement de Worker ou une commande de vérification appartient à l’Implémentation du site.
- Une composition de composants orientée vers une tâche appartient aux Motifs; la règle durable pour en créer un appartient à la Gouvernance du site.
- Un dossier de décision appartient à
/docs/adr/, sauf s’il a été réécrit comme directive actuelle.
Entretien#
Lorsqu’une page est difficile à placer, nommez d’abord la décision. Si la page explique ce qui devrait être vrai, elle relève habituellement de la gouvernance. Si elle explique comment le site le rend vrai aujourd’hui, elle relève habituellement de l’implémentation.