Décisions fondatricesADR-0021 · Academy et Centre d’aide

ADR-0021 · Academy dans l’app et Centre d’aide

Les leçons guidées vivent dans l’app (une par surface) ; le Centre d’aide reste la référence publique. Chaque leçon renvoie vers sa page, sans dupliquer ses tableaux.

Statut

Accepté · 2026-10-03

Remplace ou amende : précise l’ADR-0009, dont le « Statut de mise en œuvre » annonçait qu’une duplication de contenu entre l’Academy in-app et le Centre d’aide demanderait une ADR dédiée. Celle-ci.

Statut dans Orbit (2026-10) : en vigueur.

Contexte

L’ADR-0009 fait du Centre d’aide le hub public unique et la résidence canonique de la connaissance publique : « il ne maintient pas une seconde copie de l’Academy, des docs MCP ou des docs API ». L’app, elle, sert une Academy in-app (/academy, /academy/[slug]) pour les membres connectés. La passe finale d’Orbit a fait de cette Academy un vrai parcours : huit leçons, regroupées en cinq pistes, une par surface du produit. Elle ne peut plus être traitée comme un détail ; le texte du Centre d’aide qui affirmait qu’il n’y avait pas de seconde copie n’était plus vrai.

Décision

Deux surfaces, deux rôles, aucune duplication de référence :

SurfaceRôleQui la lit
Academy in-app (/academy)des leçons guidées, interactives, qui s’appuient sur le compte du lecteur (son rôle, ses chiffres, ses liens vers les pages de l’app) ; une leçon par surfaceles membres connectés
Centre d’aide (/help-center)la référence publique : guides pas à pas, FAQ, dépannage, MCP, API ; la page de chaque leçon en est la version publiquetout le monde

Règles :

  1. Les leçons in-app sont, dans l’ordre : Orbit de bout en bout, Brain, Alimenter le Brain (sources et encodage), Qualité et capacité, Studio, Crédits Orbit, API et MCP, Membres et rôles. Chaque leçon est une donnée (apps/web/src/team/academy.ts : identifiant, piste, durée, rôles, lien de fin) et un composant ; ses mots sont dans les deux catalogues (anglais et français).

  2. Chaque leçon renvoie vers sa page du Centre d’aide (docsPath), qui est son équivalent public. La correspondance est :

    LeçonPage du Centre d’aide
    Orbit de bout en bout/help-center/academy/getting-started/orbit-end-to-end
    Brain/help-center/academy/getting-started/brain-spaces-memories
    Alimenter le Brain/help-center/guides/encoder-ses-sources
    Qualité et capacité/help-center/academy/getting-started/quality-vs-cu
    Studio/help-center/academy/studio/getting-started
    Crédits Orbit/help-center/guides/crediter-orbit
    API et MCP/help-center/developers/mcp
    Membres et rôles/help-center/guides/inviter-des-membres

  3. Aucune leçon ne duplique un tableau de référence : une leçon n’écrit ni un prix, ni un nombre de CU, ni une limite en dur ; elle les lit dans le moteur (@orbit/engine) et renvoie à la page publique pour le reste. Un test d’app tient cela (academy.test.ts, messages.test.ts).

  4. Une page publique ne change pas d’adresse sans changer docsPath dans la même PR : le chemin de chaque page du tableau ci-dessus est un contrat entre l’app et cette documentation, tenu par scripts/audit-orbit-claims.mjs (chaque docsPath de l’app est une page publique de cette documentation).

  5. Docs reste la seule ressource externe de la barre latérale ; Academy, API et MCP sont des surfaces de l’app (AGENTS.md, règle 10).

Conséquences

  • Le Centre d’aide n’affirme plus qu’il n’existe pas de seconde copie : il dit que l’app propose des leçons guidées et que la référence publique vit ici (help-center.mdx).
  • Un changement de produit touche deux endroits : la leçon (mots et composant) et sa page publique. Le tableau ci-dessus est la liste à relire.
  • La navigation du Centre d’aide reflète les huit leçons (documentation.json et help-center/academy.mdx).
Was this page helpful?