Où vit la documentation

Le problème

La documentation racontait l'histoire de son propre développement. Le sommaire alignait « Sprint 2 », « Vague 1 », « Audit du legacy », « Vague 2 », « Les briques du quotidien » — des titres qui disent quand une chose a été faite, jamais ce qu'elle fait. Quelqu'un qui cherchait comment afficher un tableau devait deviner dans quelle vague il était tombé.

Rien ne disait non plus quelles props prend un composant. Cent trois composants, mille huit props, et pas une page pour les lire : il fallait ouvrir le code, ou cliquer dans Storybook composant par composant.

Quatre surfaces, quatre questions

Chacune répond à une question que les autres ne posent pas. C'est la règle qui les sépare, et c'est aussi ce qui empêche une information d'exister à deux endroits.

Surface	Question	Écrite par
Référence	quelles props, quels types, quels défauts	scripts/generer-reference.mjs
Catalogue	à quoi ça ressemble, dans quel état	les stories
Démonstration	à quoi ça ressemble dans un écran entier	l'application de démonstration
Ces pages	pourquoi c'est fait ainsi	des humains

La référence est écrite par le code

Les props d'un composant sont déjà décrites une fois : dans ses types et leurs commentaires. Les recopier dans du Markdown en ferait une seconde description, qui divergerait à la première prop ajoutée — sans que rien ne le signale, puisque rien ne relie les deux.

scripts/generer-reference.mjs lit donc les types et n'écrit que ce qu'il y trouve :

Ce qu'on cherche	D'où ça vient
à quoi sert le composant	le commentaire au-dessus de la fonction
comment l'utiliser	le bloc d'exemple de ce commentaire
ses props, types et défauts	les types eux-mêmes
comment l'installer	packages/registry/registry.json

L'extracteur est celui de Storybook — react-docgen-typescript. Les deux surfaces montrent donc les mêmes tableaux, sans qu'aucune ne recopie l'autre.

Les pages produites ne sont pas suivies par Git (docs/.gitignore) : ce serait le même contenu, stocké deux fois.

pnpm docs:reference   # 24 s, 103 pages

La construction du site les régénère toujours. Le serveur de développement les laisse en place si elles existent — vingt-quatre secondes à chaque démarrage pour des pages inchangées seraient vingt-quatre secondes de trop.

Une page vaut ce que vaut son commentaire

Un composant sans commentaire donnerait une page sans explication, qui retomberait sur la description anglaise du registre. Ce ne serait pas un défaut du générateur : c'est le commentaire qui manquerait, et il manquerait aussi dans l'éditeur de quiconque utilise le composant.

Les cent trois composants en ont un. Ce que chacun doit dire n'est pas ce que la signature répète déjà — « un bouton avec un libellé et un onClick » n'apprend rien — mais ce qui ne se lit pas dans le code : ce que le composant résout, et pourquoi il le résout ainsi.

Un module sans composant principal fait exception : Icons est une collection, et sa description ne peut être accrochée à aucune des douze fonctions qu'il exporte. Elle vit alors en tête de fichier, avant les imports — le seul endroit qui parle du module entier, et que le générateur lit à défaut.

pnpm check:descriptions refuse un composant sans commentaire, et la CI le lance. Il ne juge pas ce que le commentaire contient — aucun outil ne sait faire la différence entre une phrase utile et une paraphrase de la signature.

Le catalogue a neuf sections

Elles étaient seize, en deux langues, avec des doublons : Foundations et Fondations côte à côte, Data séparant Chart des autres données. Personne ne l'avait décidé — chaque story avait été écrite en recopiant la précédente, ou pas. Faute d'ordre déclaré, Storybook les triait alphabétiquement.

L'ordre va du plus général au plus assemblé :

Section	Ce qu'on y trouve
Fondations	ce qui règle le thème, la locale, le positionnement
Primitives	ce qui se pose seul — Button, Badge, Input
Saisie	tout ce qui prend une valeur
Dates et heures	calendriers, sélecteurs, durées
Données	ce qui affiche — tableaux, montants, graphiques
Retour	ce qui répond — alertes, boîtes, surfaces flottantes
Navigation	ce qui mène ailleurs
Mise en page	ce qui porte le reste
Patterns	ce qui compose tout cela en écran

L'ordre est déclaré dans apps/docs/.storybook/preview.tsx, et pnpm check:stories refuse une section hors de cette liste, un titre sans composant, ou deux stories sous le même titre. La CI le lance.

L'arborescence des pages écrites

Les documents ne portent plus de numéro. Un numéro dit l'ordre d'écriture, c'est-à-dire la seule chose dont un lecteur n'a que faire.

docs/
  demarrer/      ce que c'est, comment poser le thème
  guides/        comment faire une chose précise
  composants/    la référence — produite, non suivie par Git
  fondations/    comment c'est construit, et pourquoi
  distribution/  registre, CLI, site, validation
  decisions/     le détail d'un choix, quand il mérite d'être retrouvé
  contribuer/    conventions et outillage

Le sommaire vit dans docs/README.md, sous « ## Sommaire », groupé par titres de niveau trois. .vitepress/sidebar.ts le lit : il n'y a donc pas deux ordres de lecture qui divergent, celui de GitHub et celui du site. La référence fait exception — elle compte cent trois pages, et les énumérer à la main serait recopier une troisième fois ce que le code sait déjà.

Ce qui a été retiré

Huit comptes rendus de développement : les quatre vagues, le sprint, les deux documents d'audit et de clôture, et le relevé d'une phase. Ils décrivaient un chemin parcouru, pas un produit — et la bibliothèque est neuve : elle n'a pas d'héritage à solder.

La feuille de route a quitté le site pour ROADMAP.md, à la racine. C'est un document de planification, écrit à la deuxième personne ; il reste lisible sur GitHub, où il a sa place, plutôt que publié comme documentation.

Voir aussi

• Site, catalogue et démonstration — comment les quatre surfaces sont construites et mises en ligne.
• Source unique des composants web — la même règle, appliquée au code.