Un tutoriel, en données

Précédemment. Le site est construit, vérifié, mis en production et copiable dans une sandbox. Toutes les parties précédentes ont décrit le projet par couches ; celle-ci suit une fonctionnalité de bout en bout.

Une étude de cas prend une fonctionnalité et la traverse de part en part : les types, les données, l’état, l’affichage, l’accessibilité, les vérifications, les tests. Celle-ci suit le moteur des tutoriels interactifs : un petit module (apps/web/src/features/tours/, six cents lignes de moteur, et un fichier par tuto) qui touche presque tout ce que les parties précédentes ont décrit.

Un tutoriel ne se lit pas : il se fait. Sur la vraie page, l’écran s’assombrit, seul l’élément de l’étape en cours reste éclairé et actif, une bulle dit quoi faire, et l’on passe à l’étape suivante en faisant l’action demandée — cliquer, taper, changer de page. Le premier tuto du projet guide un administrateur dans la création d’un post — une actualité du mur de l’accueil.

Un tuto est une donnée 📋#

Le moteur ne sait rien des actualités. Il sait lire une description de tuto, écrite en données : un objet par tuto, dans son propre fichier. Ajouter un tuto, c’est écrire des données, pas du code. Le type de cette description est le contrat entre les auteurs de tutos et le moteur :

// ⚠ Fichier introuvable : apps/web/src/features/tours/tour.types.ts// Il a été déplacé ou supprimé depuis la rédaction de ce chapitre.

Le premier tuto#

// ⚠ Fichier introuvable : apps/web/src/features/tours/definitions/admin.posts.create.ts// Il a été déplacé ou supprimé depuis la rédaction de ce chapitre.

Le tuto crée un vrai article, en brouillon : il agit sur les vraies données, et le dit dans ses bulles (« vous pourrez supprimer l’article ensuite »). Un tuto qui publierait quelque chose, ou supprimerait, serait une autre affaire : il ne guiderait pas, il agirait à la place de l’utilisateur.

Des tutos partout#

Après ce premier tuto, seize autres ont suivi : pour les visiteurs et les membres, puis pour les administrateurs. Chacun a sa fiche, dans le guide du site ou dans la documentation des administrateurs, qui le lance par son identifiant :

Une règle les tient tous : un tuto n’envoie rien que d’autres verraient, et ne fait rien d’irréversible. Il montre le bouton « Envoyer » d’une demande au club, il ne le clique pas : une demande partie arrive dans la boîte du bureau, avec un accusé de réception, et ne se rattrape plus. Les deux seuls tutos qui créent quelque chose — un post, un flash info du ruban — créent un brouillon que personne d’autre ne voit, et le disent.

Le public de « Traiter une demande » est member, pas admin : un membre d’un groupe responsable d’une catégorie (le support du site) traite les demandes sans être administrateur. Le public décide de qui se voit proposer le tuto ; c’est la page qui, elle, n’affiche la boîte qu’à ceux qui traitent une catégorie.

Le registre réunit les tutos et répond à deux questions :

// ⚠ Fichier introuvable : apps/web/src/features/tours/tour.registry.ts// Il a été déplacé ou supprimé depuis la rédaction de ce chapitre.

Un contrat de nom entre le tuto et la page#

Une étape désigne son élément par un nom, pas par sa position dans la page ni par sa classe CSS. L’élément porte ce nom dans un attribut data-tour :

Une classe CSS change avec le style, un texte avec la langue ou une reformulation, une position avec la mise en page : un tuto qui s’y accrocherait casserait à chaque retouche. data-tour ne sert qu’aux tutos ; il ne change rien à l’affichage, et dit à qui modifie le composant que quelqu’un dépend de ce nom (partie « Démarrer », chapitre « Façon de travailler »).

Les noms suivent la page et le rôle de l’élément (posts.list.create, posts.form.title) : on devine, en lisant le tuto, où se trouve chaque cible.

Un nom, deux éléments#

Le header a deux visages : la barre complète sur un grand écran, un bouton de menu sur un téléphone. Le tuto « Découvrir le site » ne connaît qu’un nom, header.nav ; les deux éléments le portent, et un seul s’affiche à la fois :

Le moteur prend le premier élément visible qui porte le nom (chapitre 2). Un même tuto se suit donc sur toutes les largeurs d’écran, sans une étape par mise en page.

Une garde pour le contrat#

Un contrat que rien ne vérifie finit rompu. Renommer l’attribut, déplacer le bouton dans un autre composant, retirer un tuto du registre : le code compile, le lint ne dit rien, et le tuto se bloque chez l’utilisateur — ou n’apparaît plus. scripts/check-tour-targets.mjs, lancé par pnpm check (partie « Qualité », chapitre « Les gardes maison »), cherche trois ruptures :

Les deux dernières vérifications sont nées de la relecture de cette partie : la première seule protégeait les cibles, pas l’existence du tuto lui-même. La garde a été vérifiée comme un test (partie « Qualité ») : l’import retiré du registre, puis un identifiant mal orthographié dans une fiche, chacun a fait échouer pnpm check avec son message.

Récapitulatif#

À suivre#

Un tuto est une liste d’étapes. Le moteur doit la dérouler : se souvenir de l’étape en cours à travers plusieurs pages, trouver l’élément visé, assombrir le reste, et reconnaître l’action attendue.