Le plan d'une page de référence

Les 36 pages de référence suivent le même plan, dans le même ordre. Cette page le fixe : elle sert de contrat au lecteur — qui sait ce qu’il a le droit d’y trouver — et de gabarit au rédacteur.

La règle qui sépare la référence des guides

Une page de référence dit ce que c’est. Un guide dit comment faire.

Une procédure pas-à-pas n’a rien à faire ici : elle est liée, jamais recopiée. Une page de référence décrit un écran, ses zones, ses actions possibles et ses états ; un guide enchaîne des gestes pour atteindre un but.

Conséquence pratique : les deux se lisent indépendamment. On comprend un écran sans avoir lu le guide du rôle, et on suit une procédure sans avoir lu la page de l’écran.

Les sept sections, toujours dans cet ordre

Section	Ce qu’on y met
À quoi sert cet écran	une à trois phrases : son rôle dans le produit, pas sa description
Qui y a accès	<ScreenAccess> — permission, rôles dérivés, effet du périmètre
Ce qu’on y voit	zone par zone, chaque zone nommée
Ce qu’on peut y faire	les actions, leur permission, et le lien vers la procédure du guide
États particuliers	la check-list ci-dessous — la section qui justifie ce site
Écrans liés	<ScreenLink> vers les écrans amont et aval
Doc technique source	le sources du frontmatter, rendu en pied de page

Aucune section n’est vide. Si un écran n’a rien à dire dans une section, c’est une information : écrivez-la — « aucune action n’est possible sur cet écran : il est en lecture seule ».

Nommer les zones, pas les numéroter

Sans capture d’écran, « la zone 3 » ne repère rien. On écrit « le panneau de filtres, en tête de la grille », et la numérotation ne sert qu’à ordonner la lecture, jamais à localiser. La description textuelle porte toute la charge : elle doit être assez précise pour qu’un testeur retrouve la zone sans hésiter.

La check-list des six états

C’est la section la plus utile du site, et celle que personne d’autre n’écrit. Elle se lit en diagonale par quelqu’un de bloqué : un état par ligne, le symptôme d’abord.

État	La question à laquelle il faut répondre
Vide	aucune donnée : que voit-on, et que propose-t-on de faire ?
Chargement	squelette, indicateur, ou rien du tout ?
Erreur	réseau, serveur, données invalides : quel message exactement ?
Sans droit	l’écran est-il masqué, refusé, ou partiellement rendu ?
Partiel / obsolète	données périmées, opération en cours, résultat en attente
Hors périmètre	la permission est là, mais pas sur cette ressource

Écrivez au présent et à la forme observable. « La liste affiche Aucune salle ne correspond à ces critères sur ce créneau. » — et non « un état vide est prévu ». Si vous ne pouvez pas citer le message, c’est que l’état n’a pas été vérifié : signalez-le comme incertain plutôt que de l’affirmer.

Le cas « sans droit » mérite une précision

Le produit filtre au lieu de désactiver :

• une section absente de la navigation n’est pas un bug : l’utilisateur n’a pas le droit ;
• il n’y a pas d’entrée grisée avec un cadenas — ce qui n’est pas permis n’existe pas à l’écran ;
• au tout premier affichage, la navigation peut être plus courte le temps que les permissions arrivent.

<ScreenAccess> écrit ces trois phrases pour vous. Ne les réécrivez pas.

La règle d’URL : l’adresse de la doc se devine

L’URL de la page de référence se déduit de l’URL de l’application. C’est ce qui permet d’envoyer un lien sans le chercher, et ce qui rendra le lien retour application → documentation constructible par une règle plutôt que par une table entretenue à la main.

Route de l’application	Page de référence
/planning	/reference/planning/
/admin/roles	/reference/admin/roles/
/referential/rooms/$roomId	/reference/referential/rooms/
/pedagogy/teachers/$teacherId/availability	/reference/pedagogy/teachers/availability/
/login	/reference/public/login/

Les segments dynamiques disparaissent : une page de référence décrit un type d’écran, jamais une instance. /referential/rooms/$roomId documente donc toutes les salles à la fois.

Quand l’écran de liste occupe déjà l’adresse, le détail prend un suffixe explicite — /detail, /jobs. Ces cas sont peu nombreux et écrits comme exceptions dans src/data/screens.ts ; tout le reste est calculé. Un écran ajouté au produit sans page de documentation fait échouer bun run test.

Un exemple complet

Voici l’ossature de la page login, section par section. C’est le modèle dont les 35 autres héritent ; la page réelle est Connexion.

À quoi sert cet écran

La porte d’entrée du produit : il échange une adresse et un mot de passe contre une session, puis renvoie l’utilisateur là où il voulait aller.

Une à trois phrases. Ce que l’écran fait, pas ce qu’il contient.

Qui y a accès

Écran public — aucune session n'est nécessaire, aucune permission non plus. Il est atteignable par n'importe qui connaissant l'adresse.

Une ligne de composant. Sur un écran authentifié ce serait <ScreenAccess permission="planning.edit" />, et les rôles seraient dérivés du RBAC.

Ce qu’on y voit

Le formulaire de connexion, au centre : les champs « E-mail » et « Mot de passe », le lien « Mot de passe oublié ? » aligné à droite du second, et le bouton « Se connecter ».

Le pied de carte : « Pas encore de compte ? » suivi du lien « Créer un compte ».

Zone nommée, contenu cité exactement comme l’écran l’affiche.

Ce qu’on peut y faire

Action	Permission	Procédure
Se connecter	aucune	—
Demander une réinitialisation	aucune	la page « Mot de passe oublié »

Sur un écran authentifié, la colonne « Permission » porte un <Permission key="…" /> et la colonne « Procédure » un lien vers le guide propriétaire.

États particuliers

Ce que vous voyez	Ce que ça veut dire
« E-mail ou mot de passe invalide. »	l’un des deux est faux — le message ne dit jamais lequel
« Trop de tentatives. Patientez un instant puis réessayez. »	le limiteur de débit a répondu

Les états de la check-list, ceux qui existent. Un état par ligne, symptôme d’abord.

Écrans liés

<ScreenLink to="/reference/public/signup/" />, <ScreenLink to="/reference/public/forgot-password/" />.

Amont et aval — ce vers quoi un lecteur va réellement, pas une liste exhaustive.

Doc technique source

Rien à écrire : le pied de page rend le sources du frontmatter.

Ne décrivez jamais un état que vous n'avez pas vérifié

C’est la règle qui décide si ce site sert à quelque chose. Un message inventé, même plausible, transforme la section « États particuliers » — la seule que personne d’autre n’écrit — en source de perte de temps supplémentaire.

Deux façons de vérifier, par ordre de fiabilité : reproduire l’état dans l’application, ou lire les branches du composant de route (isLoading, error, les rendus conditionnels) et les messages correspondants. Ce que vous ne pouvez faire ni l’un ni l’autre, dites qu’il reste à confirmer.