Aller au contenu

ADR-042 : Découpler la documentation du cœur et celle des opt-ins

Statut

Accepté.

Contexte

Depuis l'ADR-038, la documentation des 12 opt-ins est embarquée dans chaque
paquet (packages/<pkg>/docs/) et agrégée au build dans le site unique
forgemvc.com par le plugin mkdocs-monorepo.
L'ADR-039 a réorganisé l'arborescence du cœur.

Dans cet état, le cœur et les opt-ins partageaient une seule navigation et
étaient fortement couplés par des liens transversaux dans les deux sens :

  • liens cœur vers opt-in (ex. docs/features/auth.md vers la référence MFA) ;
  • liens opt-in vers cœur (ex. un welcome opt-in vers le guide d'installation).

Ce couplage brouille la frontière entre le framework (cœur) et les briques
optionnelles, à rebours du principe 8 (noyau minimal, briques opt-in) et du
principe 1 (séparer framework et application).

Décision

  1. Deux navigations distinctes dans un site unique.
    La navigation se scinde en deux onglets de premier niveau
    (navigation.tabs, déjà actif) :
  • Cœur de Forge : installation, concepts, modèle de données, guides,
    référence, parcours cœur, déploiement, release, philosophie, tests
    terrain, projet ;
  • Opt-ins officiels : les 12 paquets, chacun avec sa propre
    progression et sa référence par-module.

Le site reste un seul build et une seule URL ; le découplage est de
navigation et de contenu, pas d'infrastructure.

  1. Aucun lien transversal entre les deux espaces.
    Aucune page du cœur ne lie une page d'opt-in, et réciproquement.
    Les renvois transversaux existants sont neutralisés : le texte est
    conservé, le lien est retiré.
    Les liens internes à un espace restent autorisés :
    cœur vers cœur, et opt-in vers opt-in (les opt-ins partagent le même
    onglet).

  2. Les mentions restent permises, pas les liens.
    Une page du cœur peut mentionner qu'un opt-in existe (ex. « le module
    forge-mvc-mfa fournit le MFA »), mais sans lien hypertexte vers sa
    documentation.

Conséquences

  • La navigation reflète la frontière framework / briques optionnelles.
  • Un lecteur du cœur n'est jamais détourné vers la doc d'un opt-in, et
    inversement.
  • Les parcours d'installation des opt-ins ne renvoient plus par lien vers le
    guide d'installation du cœur : l'utilisateur installe Forge d'abord, puis
    consulte l'espace opt-ins.
  • Deux garde-fous qui exigeaient un lien transversal
    (test_docs_reference_split_001, test_pivot_advanced_usage_docs_008) sont
    réécrits pour interdire ces liens au lieu de les exiger.
  • Un garde-fou nouveau vérifie l'absence de lien transversal dans les deux
    sens.

Alternatives écartées

  • Deux sites mkdocs séparés (deux builds, deux URLs) : découplage plus
    fort mais surcoût de CI et de déploiement non justifié ; un seul site avec
    deux onglets suffit à séparer les navigations.
  • Découpler la navigation seulement (garder les liens de contenu utiles) :
    écarté, le couplage par liens de contenu subsistait.