ADR-039 : Refonte de l'architecture d'information de `docs/` (cœur)¶

Statut¶

Accepté, Forge 1.0.0-beta.x (ticket ADR-DOCS-IA-001).

Exécution (tickets DOCS-IA-00x) : étape 1 (tronc « Opt-ins officiels »),
étape 2 (« Apprendre (parcours cœur) »), étape 3 (bucket « Modèle de données »)
et étape 5 (« Guides du cœur » consolidés) faites, nav-only, --strict vert.
Étape 4 (dédoublonnages) annulée après vérification : crud n'est pas un
doublon, concepts/ déjà absent (voir section Décision). Reste optionnel :
reséquencer « Apprendre » plus haut, fusionner « Premiers pas » et « Concepts »
en « Découvrir », déplacements physiques de fichiers pour aligner dossiers et
buckets (faible valeur, l'IA visible est dans la nav).

Fait suite à l'ADR-038 (doc des opt-ins embarquée par paquet) : une fois les
douze opt-ins sortis de docs/, la structure cœur héritée laisse apparaître des
doublons, des frontières floues et un regroupement de nav incomplet.
Aucun fichier n'est déplacé avant validation de la cible et exécution séquencée
(modèle anti-casse de l'ADR-038).

Date¶

2026-06-21

Contexte¶

Audit de docs/ après l'ADR-038. Problèmes constatés :

Tas plat des opt-ins dans la nav. Les douze !include figurent comme
douze entrées sœurs de premier niveau, au lieu d'un tronc unique
« Opt-ins officiels » (dette explicite laissée par l'ADR-038).
Doublons de sujet.
- features/crud.md et reference/crud.md ;
- features/migrations.md, features/migration-guide.md et
entities/migration-legacy-vers-canonique.md.
Modèle de données éclaté entre features/ (entity_architecture.md,
relations.md) et entities/ (entity-schema.md, relations-schema.md,
pivots-many-to-many.md, slugs.md, types-forge-mariadb.md,
json-canonique.md, limites-contrats-json.md, entity-validate.md,
vscode-json-schema.md).
reference/ mélange la vraie référence (api.md, api-json.md,
cli-commands.md, http.md, sessions.md, audit-auth.md,
pages-publiques.md, profils.md, public-contract-1.0.md,
runtime-errors-schema.md, vocabulaire-opt-in.md) et des pages qui n'en
relèvent pas (markdown.md, aide-mémoire Markdown ; crud.md, doublon).
features/ est un fourre-tout : guides d'usage du cœur mêlés à des pages
de référence et à des sujets périphériques (imagemagick-logos.md,
pdf.md).
Section nav trompeuse : « Modules et starters » ne contient plus que des
parcours cœur (welcome-forge, welcome-helpers, welcome-markdown) et le
hub starters/index.md.
Dossier mort : docs/concepts/ est vide.

Hors périmètre (ne pas « ranger ») :

history/ : archive brute volontaire (conventions D) ;
javascripts/ static/ stylesheets/ logos/ : assets MkDocs.

Décision (cible proposée)¶

Règle directrice : un sujet a un seul emplacement canonique, et le nom du
dossier dit sa nature (apprendre / utiliser / référencer / opérer).

Buckets de premier niveau visés pour la nav (cœur) :

Accueil, index.
Découvrir, positionnement, « Bonjour Forge », prise en main, concepts,
FAQ (regroupe guide/).
Installer, install/ (inchangé, déjà cohérent).
Apprendre (parcours), parcours cœur uniquement : welcome-forge,
welcome-helpers, welcome-markdown, plus le tutoriel applicatif complet.
Le hub starters/index.md est recentré sur le cœur (les opt-ins ont leur
propre progression dans leur paquet).
Guides du cœur, guides d'usage : auth, CRUD, front, médias, PDF,
profils, migrations (issus de features/, dédoublonnés).
Modèle de données, unifie entities/ et les pages data de features/
(entity_architecture, relations) en un seul bucket « Entités & relations ».
Référence, référence stricte uniquement (reference/ nettoyé :
markdown.md part vers « Contribuer / écrire la doc », le doublon crud.md
est supprimé au profit du guide canonique).
Déploiement, deployment/ (inchangé).
Opt-ins officiels, tronc unique regroupant les douze !include
(referme la dette de l'ADR-038).
Philosophie & contribution, philosophy/, contributing/,
architecture/.
Projet, release/, roadmap/, testing/, project/, history/.

Dédoublonnages actés :

crud : finalement pas un doublon (vérifié à l'exécution).
features/crud.md = guide « CRUD explicite » (génération) ;
reference/crud.md = « Relations avancées et CRUD enrichi » (référence
relations). Les deux sont conservés ; reference/crud.md est candidat au
bucket « Modèle de données » plutôt qu'à « Référence » (étape nav ultérieure).
migrations : fusionner features/migrations.md et
features/migration-guide.md ; entities/migration-legacy-vers-canonique.md
rejoint « Modèle de données » (fait au niveau nav, étape 3).
docs/concepts/ : déjà absent du disque, rien à supprimer.
reference/markdown.md : aide-mémoire sans lien entrant ; déplacement hors
référence reporté (faible valeur, aucun lien à recâbler).

Plan d'exécution séquencé (anti-casse)¶

Mêmes garde-fous que l'ADR-038 : déplacements par git mv, recâblage des liens
entrants, mise à jour des tests tests/meta/*, mkdocs build --strict vert à
chaque étape, et lecture du compteur pytest (pas du tail).

Quick win nav : grouper les douze !include sous « Opt-ins officiels »
(nav seulement, zéro déplacement). Referme la dette ADR-038.
Parcours : renommer/recentrer « Modules et starters » → « Apprendre »,
nettoyer le hub starters/index.md.
Modèle de données : fusionner les pages data de features/ dans un
bucket « Entités & relations » avec entities/.
Référence : sortir markdown.md, dédoublonner crud, resserrer
reference/ sur la référence stricte.
Guides du cœur : recentrer features/ sur les guides d'usage.
Découvrir / Projet : regrouper guide/ et les sections projet ;
supprimer le dossier mort concepts/.

Chaque étape est un ticket séparé (DOCS-IA-<n>), commit distinct, validé avant
le suivant. La nav (mkdocs.yml) est la source de l'IA ; les chemins disque
suivent la nav.

Conséquences¶

Positives :

Une seule porte d'entrée par sujet (principe 11 appliqué à la doc).
Frontières de dossiers lisibles (apprendre / utiliser / référencer / opérer).
Tronc opt-ins propre (dette ADR-038 close).

Négatives / coûts :

Beaucoup de git mv + recâblage de liens + mise à jour de tests meta.
Les URLs publiques de plusieurs pages cœur changent (acceptable en bêta,
pas d'utilisateurs externes à protéger, note pré-1.0 de la charte).
Risque de liens cassés : maîtrisé par mkdocs build --strict à chaque étape.

Charte appliquée¶

Principe 11, une seule façon officielle (un sujet, un emplacement).
Principe 2, petits tickets (exécution par étapes DOCS-IA-<n>).
Principe 6, tester avant d'élargir (--strict + suite meta à chaque étape).
Règle B, révéler avant de corriger (audit explicite ci-dessus).

ADR liés¶

Fait suite à l'ADR-038 (doc opt-ins embarquée) : referme la dette du tronc
de nav et range le cœur resté en place.

ADR-039 : Refonte de l'architecture d'information de docs/ (cœur)¶