Skip to Content
Meubles Morinière

Engineering choicesDécisions d’architecture(in French)4 min read

0013 · La documentation vit dans le dépôt

La doc est une troisième application Next.js du monorepo. Elle inclut les textes du dépôt et recalcule ses figures au build.

Not translated yet

This page is shown in its original French. Code excerpts, tests and figures read the same in either language.

Statut : acceptée, amendée le 13 novembre 2026 (références de la prose vérifiées) · Décidée : 13 novembre 2026 · Sources : 2fd35cdb09, 9086def499, 7703182e16, 501fc9fdee, apps/docs/next.config.ts, scripts/check-doc-references.mjs

Contexte

Le 1er septembre 2026, j’ai retiré le journal des décisions et la feuille de route. Le 5, j’ai vidé docs/ de ses doctrines, de ses patterns et de ses runbooks. À partir de là, la raison d’une règle doit être « en JSDoc à l’endroit exact du code, ou dans un scan de test/ » (9086def499). Le 13 novembre, un site de documentation arrive dans apps/docs, et les notes qui restaient dans docs/ y passent (7703182e16).

Contraintes

  • Un texte écrit à côté du code se périme sans qu’on s’en rende compte. C’est pour ça que docs/ a été vidé.
  • Les pages d’exploitation (secrets, procédures) ne doivent pas être publiées.
  • Le 9 novembre 2026, j’ai décidé de ne plus ajouter de copie à mettre à jour à la main (AGENTS.md).

Alternatives

  • Ne rien documenter en dehors du code. C’était la situation du 5 septembre. Rien ne présentait l’ensemble à un nouveau lecteur.
  • Un outil externe (wiki, Notion, GitBook). Il serait hors du dépôt, donc hors de ses contrôles.
  • Des fichiers Markdown sans site. Ils se liraient sur GitHub, mais sans inclusion vérifiée et sans figure calculée.

Décision

La doc est une troisième application Next.js. Elle utilise Fumadocs et la même stack que les deux autres : la palette de ui, les en-têtes de sécurité d’infra, l’ESLint de config. Les sections du README sont incluses, sans être recopiées. Les graphes et les chiffres sont recalculés au build à partir du dépôt. Les pages internes sont dans content/docs/interne, et elles sont absentes du build public (DOCS_INTERNAL). Un build de production Vercel qui les embarquerait échoue. Ces ADR suivent la même règle : ils nomment la source et ne la recopient pas.

Raisons

Confirmées

  • docs/ a été vidé pour deux raisons. Un rapport dont le plan est exécuté « décrit un état qui n’existe plus, et le relire coûte plus qu’il ne renseigne » (ancien journal, 24 août 2026). Et la raison d’une règle va dans le code (9086def499).
  • Les pages internes sont absentes du build. Elles ne sont pas simplement cachées : « Le domaine de production n’a pas de contrôle d’accès, seulement le noindex » (apps/docs/next.config.ts).

Hypothèses

  • On a fait un site, plutôt que rien, pour présenter l’architecture et ses choix à un lecteur extérieur au dépôt. L’accueil est bilingue et présente le produit. Mais le commit du 13 novembre ne donne pas de raison.
  • On a pris Fumadocs parce qu’il s’appuie sur Next.js et MDX, donc sur la stack qu’on avait déjà. Aucun comparatif n’est écrit.

Compromis

  • Les textes d’explication reviennent, après leur retrait du 5 septembre. Ils ne resteront justes que s’ils respectent la règle « pas de copie ». Sinon, ils se périmeront de la même façon.
  • Le build dépend de l’organisation du dépôt. Si un fichier lu par une figure de l’architecture change de place, la figure disparaît sans casser la page. Par contre, une figure de flux (apps/docs/shared/components/flows/) casse le build, comme un extrait de code.
  • Un commit qui touche aux paquets reconstruit aussi la doc (apps/docs/scripts/ignore-build.sh, sorti dans un script parce que Vercel refuse un ignoreCommand trop long, 501fc9fdee).
  • Une page qui n’a pas de traduction s’affiche en français à l’adresse anglaise.

Conséquences

  • Si un titre du README disparaît, le build de la page qui l’inclut échoue.
  • Un chemin, un fichier.ts#SYMBOLE ou un identifiant cité dans le texte doit encore exister dans le dépôt. Sinon, le push et le build de la doc échouent, et le message donne la page et la ligne (scripts/check-doc-references.mjs).
  • Une nouvelle décision d’architecture s’écrit ici, au format de ces ADR, en citant ses sources.

Risques résiduels

  • Le texte se périme sans bruit. Les inclusions, les figures et les références citées sont vérifiées. Mais une phrase qui ne décrit plus le code ne fait rien échouer.
  • Le domaine public n’a pas de contrôle d’accès, et ces pages décrivent en détail les rôles, les canaux et les gardes. Elles ne contiennent aucun secret, et la sécurité qu’elles décrivent ne repose pas sur sa discrétion. Les pages d’exploitation, elles, sont absentes du build. Elles ne sont pas juste cachées.
  • Cette doc est une liste mise à jour à la main, sections de risques comprises. Elle n’échappe pas à la règle qu’elle décrit.

Quand la revoir

  • Dès qu’une page se révèle fausse à la relecture, il faudra la réduire à ce que le code prouve, ou la retirer. C’est comme ça que docs/ a été vidé le 5 septembre.

On this page