Documenter son projet web

Ce cours t’aide à documenter un projet web que tu as déjà développé. L’objectif est qu’une autre personne puisse le lancer, le comprendre et le modifier sans tes explications à l’oral.

Tu peux travailler sur ton projet ou sur la démonstration fournie. Prépare un éditeur et un lecteur Markdown. Les schémas sont fournis en SVG, avec leurs sources textuelles Mermaid ou Mocodo. Le kit exécutable utilise Node.js 24. La génération complète du site utilise aussi Python 3.12.

L’exemple suivi dans le cours

Réserve ta place est une application fictive pour une association qui organise des ateliers de poterie. L’organisateur publie les dates et le nombre de places. Les participants choisissent un atelier et réservent une place.

Un “atelier” désigne une séance à une date précise. Une “réservation” relie une personne à cette séance.

Le kit de démonstration fournit les règles de réservation en JavaScript, des tests et des scénarios BDD. Il fonctionne en mémoire. L’interface web, PostgreSQL et l’envoi de courriels des exemples d’architecture restent fictifs. Les commandes du kit sont exécutables depuis la racine de ce dossier. Les exemples concernant ton application sont à adapter.

Parcours

Chaque chapitre explique une méthode, l’illustre et propose un exercice sur ton projet.

Tu peux aussi consulter un chapitre seul. Pour améliorer l’installation, commence par le chapitre 4. Pour expliquer le trajet d’une demande entre le navigateur et la base, ouvre le chapitre 5.

Ce que tu conserveras à la fin

Les exercices te feront travailler le README, les guides, les schémas, les données et les décisions. Tu écriras aussi un scénario métier et observeras son exécution. Améliore les documents existants lorsqu’ils répondent déjà au besoin.

Les exemples et corrigés rassemblent les résultats attendus et les fichiers de code. La sélection d’outils et de sources précise quoi générer, avec quelles limites. Les photographies, captures et schémas ont leurs crédits.

Vérifie que chaque document répond à la question annoncée dans son titre. Signale les commandes non testées et les informations que tu n’as pas pu confirmer.

Les essais se font sur des ressources locales ou de test. Les références figurent dans les chapitres concernés.

Pourquoi documenter un projet ?

Une application s’exécute sur ton ordinateur. Tu connais la commande pour la démarrer, le compte de test et les raisons du choix de stockage. Quelqu’un qui découvre le dépôt ne connaît rien de tout cela.

Explique ce qu’il faut savoir pour utiliser ou reprendre le projet :

• comment le lancer,
• quels accès sont nécessaires,
• pourquoi certains choix techniques ont été faits.

Rendre les règles compréhensibles

Prenons Réserve ta place, une application fictive pour réserver une place à un atelier de poterie. Une personne ne peut avoir qu’une réservation par atelier, même si elle l’annule ensuite.

Le code empêche les doublons, mais la raison de cette restriction peut manquer : l’association l’a-t-elle demandée ou s’agit-il d’une limite de la première version ? La réponse aide le prochain développeur à décider s’il peut autoriser une nouvelle réservation après annulation.

Documenter permet aussi de retrouver ton raisonnement après plusieurs mois et d’aider d’autres personnes à contribuer. Ce sont des usages décrits par Write the Docs.

Si tu ne connais plus la raison d’une règle, indique-le. Tu peux décrire le comportement actuel sans lui inventer une justification.

Écrire pour une personne et une tâche

Avant d’écrire une page, formule son objectif : “Cette page aide un développeur à lancer le projet sur son ordinateur.” Indique les connaissances et les accès nécessaires pour la suivre.

Décrire ce qui a été vérifié

“L’application est sauvegardée” signifie qu’une sauvegarde existe. Le fait que l’hébergeur propose cette option ne prouve pas qu’elle est activée.

Si aucune sauvegarde n’est configurée, écris :

Les données sont stockées dans la base du serveur. Aucune sauvegarde automatique n’est configurée. La restauration n’a pas été testée.

Applique la même précision aux autres vérifications. “Le formulaire a été testé au clavier” décrit un contrôle précis. “L’application est accessible” affirme beaucoup plus.

Choisir quoi documenter en premier

Commence par une information dont l’absence bloque quelqu’un : la commande de lancement, l’obtention d’un compte de test ou une règle difficile à comprendre.

Vérifie ta réponse dans le projet. Les scripts indiquent les commandes disponibles. La configuration indique les services utilisés. Les tests montrent les cas contrôlés. Une note de décision peut expliquer pourquoi une solution a été choisie.

Décris le fonctionnement actuel. Place les améliorations souhaitées dans une section distincte, avec un titre comme “Changements prévus”.

Exemple : répondre à trois collègues

Photo de Kritzolina, 2018. Elle illustre l’activité du cas fictif Réserve ta place. Source et licence.

L’organisatrice veut savoir si une place annulée redevient disponible. La personne du support veut expliquer un refus. La développeuse veut retrouver la règle qui produit ce refus. Une même fonctionnalité demande plusieurs points d’entrée.

flowchart LR
    accDescr: Trois personnes cherchent une règle, une procédure ou un point d’entrée dans le code.
    P["Participant"] --> Q["Puis-je réserver ?"]
    Q --> R["Règle métier et exemple"]
    D["Développeur"] --> L["Comment lancer le projet ?"]
    L --> G["README et guide essayé"]
    S["Support"] --> A["Pourquoi ce refus ?"]
    A --> E["Erreurs expliquées et cas testés"]

Une réponse utilisable par le support serait : “Après une annulation, la place est disponible pour une autre personne. Une nouvelle réservation de la personne qui a annulé reste refusée pour cette séance.” Ajoute le lien vers les exemples validés et le nom du rôle qui peut confirmer une évolution de cette règle.

Vérifie cette réponse dans le scénario exécutable. Le chapitre 9 explique comment faire travailler ensemble les lecteurs métier et les développeurs.

Pour ton projet, choisis une question souvent posée. Écris sa réponse en trois phrases, fais-la relire par la personne concernée et indique où elle sera retrouvée. Le critère de réussite est qu’elle puisse répondre à un cas concret sans appeler l’auteur.

Exercice : répondre à une question sans aide orale

1. Note cinq questions qu’une personne te poserait pour reprendre ton projet.
2. Pour chacune, indique où trouver la réponse ou écris “pas encore documenté”.
3. Choisis la question qui bloque le plus le démarrage ou la compréhension du projet.
4. Rédige une réponse à partir des informations vérifiées.
5. Demande à quelqu’un de la reformuler. Précise les passages qu’il a mal compris.

À discuter : quelle question revient souvent et pourrait être résolue par une page de documentation ?

Retour au sommaire

Organiser les contenus selon les besoins

Une personne qui cherche la commande de lancement doit pouvoir la trouver sans lire les comptes rendus de réunion. Organise les pages selon les questions auxquelles elles répondent.

Distinguer quatre types de documentation

La méthode Diátaxis distingue quatre types de documentation selon le besoin du lecteur.

Voici des exemples pour Réserve ta place, l’application fictive de réservation d’ateliers de poterie.

Un tutoriel accompagne une découverte. Un guide pratique suppose que le lecteur connaît déjà les bases nécessaires à sa tâche.

Choisis les types utiles à ton lecteur, sans créer systématiquement quatre pages par fonctionnalité.

Garder une procédure facile à suivre

Imagine qu’un guide de lancement contienne ce passage :

Démarre le serveur. Les connexions utilisent des sessions, car l’équipe souhaite pouvoir les révoquer. Une session conserve l’état de connexion d’un utilisateur. Sa durée de validité est configurable…

Le lecteur doit interrompre l’installation pour lire une explication sur l’authentification. Répartis les informations ainsi :

• les étapes de lancement restent dans le guide d’installation,
• le nom du paramètre et sa valeur autorisée vont dans la référence de configuration,
• les raisons du choix vont dans une page sur l’authentification.

Ajoute un lien si l’explication peut aider pendant l’installation. Nomme sa destination : “Comprendre la durée de validité des sessions” indique ce que le lecteur trouvera.

Choisir où publier

Le README présente le projet à l’entrée du dépôt. Il indique comment le lancer et mène aux autres pages. Il peut contenir toute la procédure d’installation d’un petit projet.

Un wiki permet à plusieurs personnes de modifier des pages depuis leur navigateur. Il peut convenir aux contributeurs qui n’utilisent pas Git. Si une information figure aussi dans le dépôt, choisis quelle version doit être mise à jour et remplace l’autre par un lien.

Quelques fichiers Markdown peuvent suffire si tes lecteurs peuvent les consulter et tes contributeurs les modifier.

Exemple d’organisation

Ces chemins sont des exemples à adapter dans ton projet.

Crée une page lorsqu’elle contient une réponse utile. Si quelques lignes du README suffisent, garde-les à cet endroit.

Exemple visuel : quatre pages pour une réservation

flowchart TB
    accDescr: Diátaxis distingue apprendre et travailler, puis agir et comprendre.
    subgraph APP["Pendant l'apprentissage"]
      direction LR
      T["Tutoriel : première réservation guidée"]
      E["Explication : pourquoi garder les annulations ?"]
    end
    subgraph TRAV["Pendant le travail"]
      direction LR
      G["Guide pratique : annuler une réservation"]
      R["Référence : statuts et erreurs possibles"]
    end
    T -->|"Faire"| G
    E -->|"Comprendre et consulter"| R

Dans le kit, “Réaliser sa première réservation pas à pas” serait un tutoriel. “Rejouer les scénarios BDD” est un guide pratique. La liste des paramètres de reserver est une référence. “Pourquoi conserver les annulations” est une explication appuyée sur un ADR.

Un rapport de tests peut alimenter la référence des règles. Il ne remplace pas le tutoriel qui accompagne une première utilisation. Évite de transformer le menu en liste d’outils : un collègue cherchera “Pourquoi la demande est refusée ?” avant de chercher “Cucumber”.

Pour un produit réel, crée des entrées selon les tâches des lecteurs : réserver, gérer les ateliers, intégrer l’API, intervenir en cas d’incident.

Exercice court : classe une procédure d’installation, une liste de statuts et une décision de stockage. Corrigé : guide pratique, référence, explication. Une introduction peut renvoyer vers les trois sans les recopier.

Exercice : réorganiser une page

Choisis une page de ton projet et écris la question principale à laquelle elle doit répondre.

1. Pour chaque paragraphe, note s’il aide à apprendre, à agir, à consulter un fait ou à comprendre une raison.
2. Repère un passage qui détourne le lecteur de sa tâche.
3. Déplace-le dans une section ou une page adaptée.
4. Ajoute un lien si le lecteur peut avoir besoin de ce complément.
5. Relis la page seule pour vérifier qu’aucune étape ou définition ne manque après le déplacement.

À discuter : quelle information mérite une page séparée dans ton projet, et pourquoi ?

Retour au sommaire

Écrire clairement et nommer les choses

Une consigne claire indique ce que le lecteur doit faire et comment reconnaître le résultat. Une explication claire nomme les éléments concernés et décrit leur fonctionnement.

Remplacer les appréciations par des faits

Les mots “simple”, “robuste” ou “normalement” ne disent pas comment utiliser le projet. Remplace-les par une action ou un comportement précis.

Ces exemples fictifs montrent comment formuler une information vérifiée.

Dans le guide complet, précise ce qu’il faut installer avant ces commandes et comment obtenir les valeurs de configuration.

Nommer qui fait quoi

“La donnée est validée puis enregistrée” laisse deux questions : quelle donnée et par quelle partie de l’application ?

Écris par exemple :

Le serveur vérifie qu’une place est disponible, puis enregistre la réservation dans la base.

Le lecteur peut situer le contrôle et le stockage. Ce principe rejoint les conseils de Google sur les phrases claires en rédaction technique.

Dans une consigne, utilise un verbe qui désigne une action : ouvre, copie, sélectionne, exécute. Remplace “Vérifie les paramètres” par les paramètres à consulter et les valeurs attendues.

Garder le même nom pour le même concept

Dans Réserve ta place, on réserve une place à un atelier de poterie. Garde le mot “réservation” dans tout le guide. Alterner avec “inscription” ou “commande” peut faire croire qu’il s’agit de fonctions différentes.

Si le code utilise des noms anglais, indique leur correspondance :

Limite le glossaire aux mots ambigus ou inconnus du lecteur.

Expliquer les acronymes à leur première utilisation

Écris le terme complet, l’acronyme entre parenthèses et une courte définition :

Le modèle conceptuel des données (MCD) décrit les objets du métier et leurs liens, par exemple les personnes, les ateliers et les réservations. Le MCD ne précise pas encore les types de colonnes de la base.

Utilise ensuite “MCD” dans la page. Si l’expression n’apparaît qu’une fois, tu peux te passer de l’acronyme. Le guide de Google sur les abréviations détaille cet usage.

Pour les noms anglais, ajoute aussi une définition en français.

Aider le lecteur à se repérer

Choisis des titres qui annoncent le contenu : “Configurer l’envoi des courriels” ou “Statuts des réservations”.

Numérote les étapes qui doivent être suivies dans l’ordre. Place chaque condition avant l’action concernée : “Si la base de test est vide, importe les données de démonstration.”

Accompagne les captures d’écran d’une légende et d’instructions écrites. Le lecteur doit pouvoir retrouver une règle par une recherche textuelle, même si l’interface a changé.

Exemple à exécuter et à réécrire

flowchart TB
    accDescr: Une consigne passe du contexte à l’action, au résultat attendu puis au dépannage.
    A["Consigne vague : lancer normalement"] --> B["Contexte : depuis la racine du dossier"]
    B --> C["Action : npm run demo"]
    C --> D["Résultat : trois lignes décrivent la réservation"]
    D --> E["En cas d'échec : vérifier Node et le dossier courant"]

“Lance les tests, tout devrait fonctionner” devient :

Depuis la racine du kit, avec Node.js 24 installé, lance npm test. Le résultat attendu est six tests réussis et zéro échec. Si la commande signale un module introuvable, vérifie que les fichiers du dossier demo ont bien été copiés.

Cette instruction donne un emplacement, un prérequis et un résultat observable. La procédure complète reste dans le README du kit. Lorsque le nombre de tests change, relis aussi les pages qui l’annoncent.

Pour documenter une configuration inconnue, écris “Adresse du serveur de courriel de test à obtenir auprès de l’équipe” et indique le rôle de la variable. N’invente pas une valeur qui ressemble à une configuration vérifiée.

Réécris : “Une réservation ne marche pas quand c’est plein”. Corrigé possible : “Quand le nombre de réservations confirmées atteint la capacité de la séance, une nouvelle demande est refusée avec le message Atelier complet. L’historique ne change pas.” Le test doit vérifier le refus et l’absence d’ajout.

Exercice : préciser sans inventer

Réécris ce passage :

Il suffit de configurer correctement le SMTP et de lancer normalement le backend. Le système gère ensuite automatiquement les inscriptions. En cas de problème, vérifier les paramètres.

SMTP désigne ici le protocole d’envoi des courriels, et “backend” désigne le serveur de l’application.

1. Liste les informations manquantes : paramètres, dossier, commande, comportement attendu et erreur concernée.
2. Retrouve celles que ton projet permet de vérifier. Note les autres comme “à vérifier”.
3. Rédige les consignes avec ces informations.
4. Applique la même relecture à un paragraphe de ta documentation.

À discuter : quelles informations connaissais-tu déjà sans les avoir écrites pour le lecteur ?

Retour au sommaire

Rédiger un README et des guides pratiques

Le README présente le projet et indique par où commencer. Un guide pratique décrit les étapes d’une tâche, comme lancer l’application ou exporter des réservations.

Présenter l’usage avant les technologies

Commence le README par ce que l’application permet de faire et pour qui :

Réserve ta place permet à une association de publier ses ateliers de poterie et aux participants de réserver une place.

Indique ensuite les fonctionnalités disponibles et les limites connues. Si les paiements ne sont pas gérés, précise-le avant les instructions d’installation. Présente les technologies dans une section dédiée ou dans la page d’architecture.

Préparer les instructions de lancement

Avant de rédiger, relève dans ton projet :

1. les logiciels nécessaires et les versions avec lesquelles le lancement a été vérifié,
2. les commandes d’installation des dépendances, avec le dossier où les exécuter,
3. les fichiers de configuration à créer et le rôle des variables à renseigner,
4. les étapes de préparation de la base de test, si le projet en utilise une,
5. les commandes pour démarrer les différentes parties de l’application,
6. l’adresse à ouvrir et le résultat qui confirme le démarrage.

Explique comment obtenir les comptes de test et les valeurs confidentielles nécessaires. Ne publie aucun mot de passe ni aucune clé d’accès dans le document.

Teste les étapes dans cet ordre pour repérer les dépendances ou les variables oubliées.

Structure de README à compléter

Remplace les indications de ce modèle par les données de ton projet. Supprime les sections sans objet.

# Nom du projet

Décris qui utilise l'application et pour faire quoi.

## Fonctionnalités et limites

Indique ce qui fonctionne et ce qui n'est pas encore disponible.

## Lancer le projet en local

Liste les prérequis et les accès nécessaires.
Donne les étapes de configuration et les commandes dans l'ordre.
Précise le dossier de chaque commande et le résultat attendu.

## Vérifier le fonctionnement

Donne la commande des tests existants ou un parcours manuel à suivre.

## Comprendre et modifier le projet

Ajoute les liens vers l'architecture, les données et les décisions.

## Maintenance et contribution

Indique où trouver les procédures de maintenance,
signaler un problème et proposer une modification.
Précise la licence si une licence a été choisie pour le projet.

Si le guide d’installation est déjà dans une autre page, ajoute un lien dans le README. Garde une seule version des étapes à maintenir.

Rédiger un guide pour une tâche précise

Choisis un titre qui annonce le résultat, par exemple “Exporter les réservations confirmées”. Indique la situation de départ, puis les étapes et le résultat à contrôler. C’est l’objectif d’un guide pratique dans Diátaxis.

Voici un exemple fondé sur une interface fictive de Réserve ta place.

Exporter les réservations confirmées d’un atelier

Connecte-toi avec un compte organisateur. Cette procédure télécharge la liste des réservations confirmées pour un seul atelier de poterie.

1. Ouvre l’atelier concerné. Vérifie son titre et sa date.
2. Sélectionne Réservations.
3. Dans le filtre Statut, garde uniquement Confirmée.
4. Note le nombre total de réservations correspondant au filtre.
5. Sélectionne Exporter la sélection. Dans cet exemple, ce bouton exporte toutes les réservations correspondant au filtre.
6. Ouvre le fichier téléchargé. Vérifie que le nombre de lignes de données correspond au total noté, sans compter la ligne des noms de colonnes.

Si la liste est vide, vérifie l’atelier et le filtre sélectionnés. Conserve le fichier dans un emplacement accessible uniquement aux personnes autorisées à consulter ces données.

Préciser les conditions avant les actions

Si une étape ne concerne qu’une base vide, indique-le avant la commande. Si plusieurs configurations sont possibles, sépare les parcours et précise comment choisir le bon.

Une commande qui efface des données doit être isolée des étapes de lancement habituel. Avant de la présenter, explique quelles données seront supprimées, comment vérifier la base ciblée et quelle sauvegarde préparer. Les essais du cours se font uniquement en local ou sur un environnement de test.

Exemple fourni : un README que l’on peut essayer

Le README de la démonstration est un exemple complet : usage, périmètre, prérequis, commandes, résultats attendus et dépannage. Ouvre-le avec un collègue qui n’a pas préparé le dossier.

flowchart TB
    accDescr: Parcours de lancement du kit et vérification du résultat.
    A["Ouvrir le dossier"] --> B["Vérifier Node 24"]
    B --> C["npm run demo"]
    C --> D["npm test"]
    D --> E["Comparer le résultat attendu"]

Les règles métier seules se lancent sans installer de dépendance :

npm run demo
npm test

La première commande affiche une création, une annulation et le refus d’une nouvelle réservation. La seconde doit réussir six tests. La construction du site et le BDD nécessitent l’installation supplémentaire décrite dans le README.

À faire : cacher les explications de l’auteur, suivre la procédure et noter le premier blocage. Complète le README à partir de ce blocage. Si l’environnement ne correspond pas aux prérequis, note la différence au lieu de conclure que toutes les installations fonctionnent.

Exercice : écrire et faire suivre un guide

Choisis une tâche de ton projet. Note son public, la situation de départ, les accès nécessaires et le signe de réussite.

Rédige les étapes, puis demande à quelqu’un de les suivre sans aide orale. Note les arrêts et les erreurs. Corrige les informations manquantes et fais reprendre les étapes concernées.

À discuter : à quel moment le lecteur peut-il affirmer qu’il a terminé la tâche ?

Retour au sommaire

Représenter l’architecture avec C4

Un schéma d’architecture montre les parties de l’application et leurs échanges, par exemple le trajet d’une réservation du navigateur à la base.

C4 propose quatre niveaux de détail : contexte, conteneurs, composants et code. Son nom vient des termes anglais Context, Containers, Components, Code. Choisis les vues selon la question à expliquer. Les vues de contexte et de conteneurs suffisent à de nombreuses équipes, selon le site officiel C4.

Montrer les utilisateurs et les services externes

Dans la vue de contexte, représente l’application par un seul bloc. Place autour les personnes et les services qui interagissent avec elle.

Pour Réserve ta place, l’application fictive de réservation d’ateliers de poterie :

• le participant utilise l’application pour réserver une place,
• l’organisateur l’utilise pour publier un atelier et consulter les réservations,
• l’application demande à un service externe d’envoyer les courriels de confirmation.

Relie ces éléments avec des flèches nommées : “Réserve une place”, “Publie un atelier”, “Demande l’envoi d’une confirmation”. La base de données et le serveur seront détaillés dans la vue suivante.

Montrer les applications et les stockages

Un conteneur C4 désigne une application ou un stockage, par exemple un serveur applicatif ou une base de données. Il ne correspond pas nécessairement à un conteneur Docker. La définition officielle donne plusieurs exemples.

Retenons cette architecture fictive pour Réserve ta place :

Trace une frontière autour de l’application dans le navigateur, du serveur et de la base. Le service de courriels reste à l’extérieur. Cette frontière regroupe les éléments du système étudié, indépendamment de leur hébergement.

Adapte le dessin au projet. Un site qui génère ses pages sur le serveur peut ne pas avoir d’application navigateur distincte. Indique les technologies et les protocoles que tu as vérifiés.

Détailler une partie seulement si nécessaire

Une vue des composants peut montrer, à l’intérieur du serveur, les parties chargées du contrôle d’accès, des réservations et de l’accès aux données. Elle aide à repérer où modifier une règle.

Un composant C4 regroupe du code qui remplit une responsabilité. Il ne correspond pas automatiquement à un fichier ni à un composant d’interface React ou Vue.

Pour une règle courte, un lien vers la fonction et quelques phrases peuvent suffire. Ajoute un schéma si les relations entre fonctions ou classes sont difficiles à suivre.

Dessiner et rendre le schéma lisible

Dans Excalidraw, crée un cadre par vue.

1. Donne un titre qui précise l’application, la vue et l’état représenté, par exemple “Réserve ta place : conteneurs, état actuel”.
2. Nomme chaque élément et décris son rôle. Ajoute sa technologie dans la vue des conteneurs.
3. Oriente les flèches et nomme les échanges.
4. Dessine les frontières et nomme les services externes. La couleur seule ne suffit pas à les distinguer.
5. Conserve le fichier modifiable et un export lisible depuis la documentation.

Ajoute une description textuelle du fonctionnement. Les flèches d’une vue statique montrent les relations. Pour expliquer l’ordre des appels d’une réservation, utilise une description numérotée ou un schéma de scénario séparé.

Deux vues prêtes à lire et à modifier

Ces vues décrivent l’application web fictive. Le kit exécutable ne contient que ses règles en mémoire.

Source Mermaid de la vue de contexte.

Source Mermaid de la vue de conteneurs. Un conteneur C4 désigne ici une application ou un stockage. Il ne signifie pas nécessairement un conteneur Docker.

Mermaid propose bien une syntaxe C4. Sa documentation officielle la signale encore comme expérimentale lors de la vérification de septembre 2026. Le kit fixe la version du moteur et conserve le SVG. Pour un ensemble de vues issues d’un modèle commun, examine Structurizr ou LikeC4.

Montrer un échange et un cas d’échec

sequenceDiagram
    accDescr: Séquence illustrative d’une demande de réservation acceptée ou refusée.
    autonumber
    actor P as Participant
    participant N as Navigateur
    participant S as Serveur
    participant B as Base
    P->>N: Demander une place
    N->>S: Envoyer la réservation
    S->>B: Contrôler et réserver dans une transaction
    alt Place attribuée
        B-->>S: Réservation enregistrée
        S-->>N: Réservation confirmée
    else Atelier complet ou doublon
        B-->>S: Attribution refusée
        S-->>N: Erreur métier expliquée
    end
    Note over S,B: Scénario de conception : stratégie transactionnelle à définir

Source de la séquence. Ce dessin propose un comportement à discuter. La gestion transactionnelle des accès concurrents reste à concevoir dans une application réelle.

Exercice : ajoute un service d’export aux deux vues C4, nomme son échange puis régénère les SVG avec npm run docs:diagrams. Vérifie qui utilise ce service et quelles données sortent de l’application.

Un diagramme Mermaid écrit à la main reste un modèle à maintenir. Le graphe des imports du kit, lui, est extrait du code. Il ne permet pas de déduire tous les utilisateurs, services externes ou raisons des choix d’architecture.

Exercice : suivre une action dans ton projet

Dessine une vue de contexte et une vue des conteneurs. Choisis ensuite une action, comme envoyer un formulaire.

Retrouve dans le code les appels, les routes du serveur et les accès aux données qu’elle déclenche. Corrige les échanges du schéma si nécessaire.

Demande à quelqu’un de montrer où la demande est reçue, où elle est vérifiée et où les données sont conservées. Précise le dessin si ces réponses restent ambiguës.

À discuter : quelle question nécessiterait une vue plus détaillée de ton projet ?

Pour voir une présentation du modèle : Visualising software architecture with the C4 model.

Retour au sommaire

Documenter les données avec Merise

La page d’architecture indique où les données sont stockées. La documentation des données explique ce qu’elles représentent et quelles règles elles doivent respecter.

Pour Réserve ta place, qui permet de réserver une place à un atelier de poterie, il faut préciser à qui appartient une réservation et si une personne peut en créer plusieurs pour le même atelier.

Merise est une méthode de conception des systèmes d’information. Ce chapitre en utilise les modèles de données pour passer des règles du métier aux tables d’une base relationnelle.

Distinguer les trois modèles

Le chapitre 1 du cours de bases de données de l’Université Clermont Auvergne détaille le passage du MCD au modèle relationnel.

Écrire les règles avant de dessiner

Dans notre exemple :

• une personne peut réserver une place dans plusieurs ateliers,
• chaque réservation concerne une seule personne et un seul atelier,
• une personne ou un atelier peut n’avoir aucune réservation,
• une personne ne peut avoir qu’une réservation par atelier, même après annulation,
• une réservation possède un identifiant, une date de création et un statut : confirmée ou annulée.

La quatrième règle empêche de créer une nouvelle réservation après annulation. Si ton application l’autorise, adapte la règle et sa contrainte d’unicité.

Construire le MCD et lire les cardinalités

Une entité représente un type d’objet, comme Personne, Atelier ou Réservation. Ses propriétés décrivent cet objet : un atelier possède un titre, une date et une capacité. Une association relie les entités, par exemple “Personne effectue Réservation”.

Une cardinalité indique le nombre minimal et maximal de participations d’un objet à une association. 0,N signifie zéro à plusieurs. 1,1 signifie exactement une.

Dans Excalidraw, dessine les trois entités et les deux associations. Ajoute leurs propriétés et leurs identifiants. Place les cardinalités près des entités auxquelles elles se rapportent. Les clés étrangères seront ajoutées au MLD.

Traduire les liens dans le MLD

Une clé primaire identifie une ligne de table. Une clé étrangère relie ici une réservation à une personne ou à un atelier existant.

Dans reservations, personne_id référence personnes.id et atelier_id référence ateliers.id. Ces deux valeurs sont obligatoires. Le couple (personne_id, atelier_id) doit être unique pour empêcher une seconde réservation de la même personne au même atelier.

Adapte ces noms au projet et indique leur correspondance, par exemple bookings pour les réservations.

Un lien plusieurs-à-plusieurs se traduit par une table intermédiaire. Ici, reservations relie les personnes et les ateliers. Ce chapitre ne couvre pas les associations à trois entités ni les autres cas complexes.

Vérifier le MPD dans le projet

Consulte le schéma de la base et les migrations, les fichiers qui décrivent ses modifications successives. Vérifie que les migrations attendues ont été appliquées à la base examinée.

Un outil de mapping objet-relationnel (ORM) fait correspondre les objets du code aux tables. Ses modèles aident à lire la structure prévue, mais il faut vérifier les migrations appliquées à la base.

Pour une réservation, vérifie notamment :

• les types des identifiants et de la date,
• les colonnes obligatoires,
• les clés étrangères et la contrainte d’unicité,
• les valeurs autorisées pour le statut,
• le comportement lors de la suppression de la personne ou de l’atelier.

La documentation PostgreSQL sur les contraintes explique les mécanismes correspondants. Dans ta page, fais des liens vers les fichiers du projet au lieu de recopier tout le schéma.

La capacité demande un contrôle supplémentaire. Si deux personnes réservent la dernière place en même temps, le logiciel doit empêcher de confirmer les deux demandes. Indique où ce cas est traité ou note qu’il reste à vérifier.

Si ton projet n’utilise pas de base relationnelle

Décris les objets, leurs identifiants, leurs liens et leurs règles de validation. Précise où ils sont conservés, pendant combien de temps et comment l’application y accède. Tu peux utiliser un MCD sans le traduire en tables.

Comparer un MCD à un schéma relationnel

Ce MCD est généré depuis le texte Mocodo. Une Personne participe à zéro ou plusieurs associations Effectuer. Une Réservation y participe exactement une fois. Le même raisonnement relie Réservation à Atelier. Lis les cardinalités du point de vue de l’entité à laquelle elles sont attachées.

erDiagram
    accDescr: Schéma relationnel des tables Personne, Reservation et Atelier avec leurs clés.
    Personnes ||--o{ Reservations : effectue
    Ateliers ||--o{ Reservations : concerne
    Personnes {
      int id PK
      string nom
    }
    Ateliers {
      int id PK
      string titre
      datetime date_atelier
      int capacite
    }
    Reservations {
      int id PK
      datetime date_creation
      string statut
      int personne_id FK
      int atelier_id FK
    }

Le texte Mermaid ER représente ici les tables du modèle relationnel. Cette notation ne remplace pas la notation Merise du premier dessin. Il faut encore préciser la contrainte unique sur le couple personne_id, atelier_id. Les deux cardinalités un-à-plusieurs ne suffisent pas à l’exprimer.

Les types du dictionnaire doivent préciser les unités et conventions. Une capacité est un entier de places. Une date de séance doit distinguer la date civile d’un instant avec fuseau. Le statut annulé conserve la réservation et ne consomme pas de place. Le kit JavaScript illustre cette dernière règle, mais ne met pas en œuvre les tables proposées.

Second terrain d’exercice : une bibliothèque d’objets

La ressource Bibi d’objets présente notamment les données Adhérent, Objet, Emprunt et Catégorie. Le mémento Merise permet de revoir le passage du dictionnaire au MCD puis au MLD et au MPD.

À partir de ces données, écris deux emprunts successifs du même objet par le même adhérent. Un emprunt doit pouvoir être distingué du précédent, par exemple par son identifiant. Une contrainte unique sur le seul couple adhérent-objet empêcherait ces deux occurrences. La règle d’unicité de Réserve ta place ne se transpose donc pas automatiquement.

Précise aussi si “date de retour” est la date prévue ou le retour effectivement constaté. Si les deux sont utiles, nomme-les séparément. Demande si un objet peut appartenir à plusieurs catégories avant de choisir la cardinalité. Ces réponses sont des décisions du métier, aucune génération de SQL ne les invente.

Pour reproduire les schémas, utilise les commandes du kit. Mocodo génère depuis un modèle textuel. SchemaSpy inspecte une base existante. Leurs entrées et leurs questions sont différentes.

Exercice : vérifier une relation

1. Choisis trois objets de ton application et écris leurs règles en phrases.
2. Dessine leurs liens et les cardinalités du MCD.
3. Si la base est relationnelle, montre la traduction en tables et en clés.
4. Retrouve une relation dans la base. Vérifie si elle peut être absente, dupliquée ou supprimée.
5. Note les écarts entre la règle attendue et le comportement observé.

À discuter : quelle règle est expliquée dans ta documentation mais n’est pas encore garantie par l’application ?

Retour au sommaire

Documenter les décisions et le code

Une note de décision conserve les raisons d’un choix technique. Elle aide à comprendre les contraintes de l’équipe avant de modifier sa solution.

Conserver une décision technique

Un Architecture Decision Record (ADR) est une courte note qui décrit une décision d’architecture, son contexte et ses conséquences. Le format présenté par Michael Nygard rassemble ces informations autour d’une seule décision.

Rédige un ADR pour un choix qu’une autre personne pourrait vouloir réexaminer : moteur de base de données, authentification, hébergement ou dépendance importante. Une convention déjà expliquée peut être référencée sans créer une nouvelle note.

Exemple : expliquer le choix de PostgreSQL

L’application fictive Réserve ta place stocke les réservations d’ateliers de poterie dans PostgreSQL. Voici une raison possible, inventée pour l’exemple :

Décision : utiliser PostgreSQL pour les données de réservation.

Statut : accepté dans cet exemple fictif.

L’association dispose d’un service PostgreSQL et l’équipe connaît son administration. Nous choisissons ce moteur pour les personnes, les ateliers et les réservations. Aucune comparaison avec un autre moteur n’a été menée.

L’équipe réutilise ainsi un service qu’elle administre déjà. Le développement local demande une base de test accessible. La configuration des sauvegardes et le test de restauration restent à vérifier.

Le service existant explique le choix. “PostgreSQL est performant” ne donnerait pas cette information.

Modèle de note à adapter

# 001 : [Choix technique retenu]

Statut : [proposé, accepté ou remplacé par un lien vers une autre note]
Date de rédaction : [date]
Date de décision : [date ou inconnue]
Note rédigée après la décision : [oui ou non]

## Contexte

Décris le besoin et les contraintes au moment du choix.

## Décision

Indique la solution choisie et la partie du projet concernée.

## Alternatives envisagées

Nomme les autres solutions étudiées et les raisons de leur abandon.
Si aucune comparaison n'a eu lieu, indique-le.

## Conséquences

Décris ce que ce choix apporte et les limites qu'il impose.
Distingue les résultats observés des bénéfices attendus.

## Sources et points à vérifier

Ajoute les liens vers le code, la configuration ou les échanges conservés.
Indique les informations que tu n'as pas pu retrouver.

Sépare les raisons confirmées des hypothèses. “Je connaissais cet outil et le délai était court” suffit si c’est la raison réelle du choix.

Quand le choix change, conserve la note précédente, marque-la comme remplacée et ajoute un lien vers la nouvelle décision.

Expliquer une règle locale avec un commentaire

Un commentaire est utile lorsqu’une contrainte n’est pas compréhensible en lisant les instructions seules.

// L'association accepte les demandes jusqu'à l'instant de clôture inclus.
return requestedDate <= closingDate;

Cet exemple suppose que les deux valeurs représentent des instants comparables. Le commentaire explique pourquoi l’égalité est acceptée. Un commentaire comme // compare les dates répéterait seulement l’instruction.

Place l’explication près du code concerné. Si elle porte sur toute l’architecture, écris-la dans une page dédiée et ajoute un lien si nécessaire.

Décrire ce qu’une fonction ou une route garantit

Le contrat d’une fonction décrit ce qu’on lui transmet, ce qu’elle renvoie, les erreurs possibles et les données qu’elle modifie. Il permet de l’utiliser sans lire toute son implémentation.

Pour une route, c’est-à-dire un point d’entrée du serveur, documente :

Par exemple, une route de réservation doit préciser comment elle répond lorsqu’il ne reste aucune place. Décris les cas réellement traités par le code.

Si une référence générée existe, vérifie-la et ajoute un exemple d’utilisation au lieu de la recopier.

Exemple complet : une décision avec son diagramme

Lis l’ADR 001 sur la conservation des annulations. Il relie le contexte, les options, le choix, ses conséquences et les tests correspondants.

stateDiagram-v2
    accDescr: États conservés par la décision : une réservation confirmée peut être annulée, sans être recréée.
    [*] --> Confirmée : place attribuée
    Confirmée --> Annulée : annulation
    note right of Annulée
      La réservation reste dans l'historique.
      Une nouvelle création pour le même couple
      personne / atelier est refusée.
      La réactivation n'est pas proposée dans la démo.
    end note

Le texte Mermaid de cet ADR conserve l’état du modèle à la date de la décision. Si une réactivation est ensuite acceptée, ajoute un nouvel ADR qui remplace celui-ci et relie les deux. Le diagramme de référence courante peut évoluer, tandis que le schéma historique garde son sens.

Samuel Rozé, Living Documentation, 2020. Capture fournie pour le cours, crédits et conférence.

Retrouver une modification et générer une référence

Dans un dépôt qui possède des commits, ces commandes permettent de chercher l’historique du fichier :

git blame -w -- demo/src/reservations.mjs
git log -p -- demo/src/reservations.mjs

Ouvre ensuite le commit identifié avec git show suivi de son identifiant. Le git blame officiel attribue les lignes à des révisions. Son résultat ne donne pas automatiquement le raisonnement de la décision. Lis le message, la proposition de changement et l’ADR associés. Si le dossier du cours n’a pas d’historique Git, fais cet essai dans un dépôt jetable.

Pour la référence du code, lance npm run docs:api après installation. reserver et annuler comportent des annotations JSDoc sur les paramètres, effets et erreurs. La génération extrait ces informations. Les tests vérifient les comportements couverts.

Exercice : explique pourquoi le message “Réservation déjà existante” peut arriver alors qu’il reste une place. Le doublon est contrôlé indépendamment de la capacité et inclut les réservations annulées. Si ce choix ne convient plus au métier, propose une évolution de la règle et de l’ADR.

Exercice : documenter un choix et une règle

Pour apprendre à afficher les descriptions et les types directement au survol dans VS Code, suis la manipulation JSDoc, TSDoc et TypeDoc. Elle fournit un appel JavaScript documenté, une variante TypeScript et un mauvais type à faire détecter. L’aide dans l’éditeur et la référence publiée réutilisent les informations placées près du code.

Choisis une décision de ton projet. Retrouve ses raisons dans les échanges ou les fichiers conservés, puis rédige un ADR. Signale les raisons que tu n’as pas pu confirmer.

Relis ensuite une fonction ou une route. Ajoute l’information qui manque pour la comprendre ou l’utiliser. Choisis son emplacement selon ce qu’elle décrit : un commentaire, une référence ou une page d’architecture.

À discuter : quel changement dans le projet justifierait de réexaminer la décision documentée ?

Retour au sommaire

Vérifier et maintenir la documentation

Fais suivre le guide d’installation par une personne qui découvre le projet. Tu verras si les étapes suffisent sans ta propre configuration.

La relecture porte sur la compréhension. L’essai vérifie que la procédure donne le résultat annoncé.

Observer sans compléter les instructions à l’oral

Choisis une personne qui possède les connaissances annoncées par le document. Donne-lui une tâche et laisse-la suivre les instructions.

Quand elle s’arrête, note l’étape et la difficulté : commande absente, mot inconnu ou mauvais lien, par exemple.

Si la difficulté vient d’un prérequis, ajoute ce prérequis au début du document et indique où l’acquérir. Si une instruction est ambiguë, réécris-la puis fais reprendre l’étape.

Préparer un essai sur un environnement de test

Pour tester une installation, utilise si possible une nouvelle copie du dépôt et une base réservée aux essais. Vérifie l’adresse de la base ciblée avant d’appliquer des migrations ou d’importer des données.

Conserve le travail existant et utilise des données fictives. Transmets les accès confidentiels par le moyen prévu dans le projet, sans les publier dans le guide.

Si tu peux seulement relire la procédure sur ta machine, indique cette limite : “Procédure relue, lancement depuis une nouvelle installation non testé.”

Noter les résultats

Note la date, la version du projet, l’environnement de test et les observations :

Après l’essai, inscris le résultat dans la dernière colonne. Note séparément les erreurs du logiciel à corriger.

Mettre à jour les documents avec le projet

L’approche Docs as Code consiste à versionner et relire la documentation avec des pratiques proches de celles du code. Elle peut se limiter à des fichiers Markdown conservés dans le dépôt. Write the Docs décrit cette approche.

Lorsqu’une modification du projet change une information documentée, corrige les pages concernées dans la même proposition de changement.

Les vérifications automatiques peuvent repérer des liens cassés ou tester des commandes. Une relecture reste nécessaire pour vérifier que les explications correspondent au fonctionnement du projet.

Éviter les copies qui ne sont plus à jour

Conserve une seule procédure d’installation et ajoute des liens depuis les autres pages. Pour les détails des tables, renvoie vers le schéma ou les migrations du projet.

Garde les explications qui complètent ces fichiers. Une migration peut ajouter une colonne statut. La documentation explique ce que chaque statut signifie pour l’utilisateur.

Préparer la maintenance

Une page de maintenance doit indiquer où lire les journaux du serveur, comment vérifier que le service répond, où trouver la procédure de déploiement et quelles sauvegardes sont configurées.

Pour la restauration, indique le résultat du dernier essai ou “Restauration non testée”.

Une chaîne de vérification fournie

flowchart TB
    accDescr: La chaîne exécute les tests, génère les références et diagrammes, vérifie les liens et construit le site avant relecture.
    A["Modification du projet"] --> B["Tests métier et scénarios BDD"]
    B --> C["Référence JSDoc et dépendances extraites"]
    C --> D["Schémas rendus et liens vérifiés"]
    D --> E["Construction MkDocs stricte"]
    E --> F["Archive de documentation à relire"]
    F --> G["Relecture technique et métier"]

Le kit fournit un workflow GitHub Actions à placer dans .github/workflows/documentation.yml dans le dépôt qui hébergera le cours. Il exécute les tests, génère les pages et conserve le site comme artefact de construction. Il ne publie pas automatiquement un site public. Son exécution sur GitHub doit être vérifiée après l’ajout au dépôt.

Pour commencer localement :

npm test
npm run test:bdd
npm run check:links

La procédure complète génère ensuite les références, les diagrammes et le site MkDocs en mode strict. Le contrôle de liens local vérifie les fichiers visés. Il ne valide ni les ancres de titres ni la disponibilité des sites externes. Le mode strict de MkDocs complète la vérification de construction, sans garantir le sens de la documentation.

Associe une version du code et une date d’exécution au rapport que tu partages. Un rapport vert enregistré la semaine dernière ne prouve rien sur une modification effectuée ce matin.

Montrer un défaut détecté

npm run demo:regression

Cette démonstration prépare une copie temporaire du code, remplace le contrôle de capacité “supérieur ou égal” par “strictement supérieur” et exécute les tests. Deux tests doivent échouer dans la copie. Le script confirme ensuite que le défaut préparé a été détecté et termine avec succès. Le code de travail reste intact.

Quelle phrase de la documentation devient fausse ? Une demande peut désormais dépasser la capacité. Un test qui vérifie uniquement la création de la première réservation ne détecterait pas ce défaut.

Pour relier les tests aux discussions métier et aux pages consultées par les autres collègues, poursuis avec la documentation vivante et le BDD.

Exercice : faire reprendre le projet

Donne ta documentation à une autre personne et demande-lui de :

1. expliquer à qui sert l’application,
2. la lancer dans l’environnement de test prévu,
3. suivre une demande depuis l’interface jusqu’au stockage,
4. expliquer une règle de données,
5. retrouver la raison d’un choix technique et une limite de ce choix,
6. repérer où commencer une modification, sans la réaliser.

Note les blocages, corrige les deux plus importants et fais reprendre les étapes concernées. Conserve les autres points à traiter.

Relire avant de partager

• Les noms gardent le même sens et les acronymes spécialisés sont expliqués.
• Chaque consigne indique une action et le résultat à vérifier.
• Les liens mènent aux documents annoncés.
• Les schémas précisent l’application et l’état représentés.
• Les exemples et les captures ne contiennent aucun secret.
• Les résultats des essais sont distingués des vérifications restantes.

À discuter : quel prochain changement du projet demandera une mise à jour de cette documentation ?

Retour au sommaire

Faire vivre la documentation avec le projet

Une règle de réservation apparaît dans une discussion, un test, du code et un guide. Si ces représentations évoluent séparément, elles peuvent finir par se contredire. La Living Documentation cherche à conserver et partager cette connaissance avec un effort d’entretien adapté.

À la fin de ce chapitre, tu sauras expliquer une règle par des exemples, relier un scénario à du code exécuté et choisir quelles informations générer. Le kit JavaScript fournit les fichiers nécessaires. Il représente les règles de réservation en mémoire, sans interface web, serveur HTTP ni base PostgreSQL.

flowchart TB
    accDescr: Le besoin métier alimente des exemples, des scénarios et du code. Les résultats et les décisions alimentent une documentation qui revient dans les discussions.
    A["Besoin discuté avec le métier"] --> B["Exemples convenus"]
    B --> C["Scénarios exécutables"]
    C --> D["Code et tests"]
    D --> E["Documentation construite"]
    E --> A
    F["ADR : raisons et conséquences"] --> E
    D --> G["Référence et dépendances extraites"]
    G --> E

Le livre Living Documentation de Cyrille Martraire, paru en 2019, propose notamment de réutiliser les connaissances existantes et de prévoir comment leur exactitude sera entretenue. La collaboration et la lisibilité comptent autant que la génération de pages.

Choisir la source qui fait autorité

Le code montre un comportement actuel. Les personnes du métier confirment le comportement souhaité. Un ADR conserve les raisons d’une décision. Choisis la source selon la question.

Un comportement observé peut être un défaut. Une information générée peut être incomplète. Il faut donc aussi savoir ce que la source permet de conclure.

Découvrir le BDD par une conversation

BDD signifie Behaviour-Driven Development, ou développement guidé par le comportement. Une personne qui connaît le métier, une personne qui développe et une personne qui cherche les cas limites examinent ensemble une petite fonctionnalité. Ces perspectives peuvent être tenues par trois personnes ou réparties autrement dans l’équipe.

Le processus décrit par Cucumber articule la découverte du besoin, la formulation d’exemples et leur automatisation. Commence par la conversation. Installer Cucumber ne remplace pas cette étape.

Pour Réserve ta place, pose une question précise : “Que se passe-t-il quand une personne annule puis veut revenir ?” Plusieurs réponses sont possibles : créer une seconde réservation, réactiver la précédente ou refuser. Le cours retient le refus d’une nouvelle création et ne propose pas de réactivation dans sa démonstration.

Organiser les exemples

L’Example Mapping consiste à distinguer le besoin, les règles, les exemples et les questions ouvertes. Les cartes ont des couleurs conventionnelles, mais leurs libellés doivent suffire à les comprendre. Méthode officielle.

flowchart TB
    accDescr: Un besoin de réservation, deux règles, trois exemples et une question ouverte sur la réactivation.
    S["Besoin : réserver une place à un atelier"]
    S --> R1["Règle : respecter la capacité"]
    S --> R2["Règle : un seul enregistrement par personne et séance"]
    R1 --> E1["Exemple : 1 place libre, Alice est acceptée"]
    R1 --> E2["Exemple : 0 place libre, Bob est refusé"]
    R2 --> E3["Exemple : Alice a annulé, sa nouvelle demande est refusée"]
    R2 --> Q["Question : autoriser la réactivation de la réservation ?"]
    classDef besoin fill:#fff2b3,stroke:#6b5b24,color:#202020
    classDef regle fill:#dceeff,stroke:#335c85,color:#202020
    classDef exemple fill:#def2df,stroke:#376c3b,color:#202020
    classDef question fill:#fbe0dc,stroke:#88493e,color:#202020
    class S besoin
    class R1,R2 regle
    class E1,E2,E3 exemple
    class Q question

Classe les contributions. “Il reste une place, Alice réserve” est un exemple. “Ne pas dépasser la capacité” est une règle. “Une annulation permet-elle de revenir ?” est une question à résoudre.

Cette photo montre une collecte de besoins au WikiMuc, pas une séance BDD. Elle peut servir à discuter de la façon de conserver le résultat d’un atelier. Crédit : Jan Dittrich (WMDE), source et licence.

Formuler un scénario lisible

Gherkin est un langage structuré pour écrire des exemples. Les mots-clés existent en français. Dans ce scénario, “Étant donné” décrit la situation de départ, “Quand” l’action et “Alors” le résultat attendu.

# language: fr
Fonctionnalité: Réserver une place à un atelier
  Scénario: Refuser une réservation lorsque l'atelier est complet
    Étant donné un atelier de 1 place
    Et Bob possède une réservation confirmée
    Quand Alice réserve une place
    Alors la demande est refusée avec "Atelier complet"
    Et l'historique contient 1 réservation

Évite de décrire des clics, des sélecteurs CSS et chaque détail d’écran lorsque tu veux expliquer une règle métier. Ces détails appartiennent au code qui réalise les étapes. La référence Gherkin explique les mots-clés et la correspondance avec ce code.

Le fichier complet de scénarios couvre la dernière place, l’atelier complet, le retour après annulation et la place libérée pour une autre personne.

Relier le texte au logiciel

Une définition d’étape associe une phrase à une action ou une assertion. Ici, l’action appelle la vraie fonction de la démonstration.

When('Alice réserve une place', function () {
  try {
    this.resultat = reserver(this.historique, {
      personne: 'Alice', atelier: 'poterie', capacite: this.capacite
    });
  } catch (erreur) {
    this.erreur = erreur;
  }
});

Then('la demande est refusée avec {string}', function (message) {
  assert.equal(this.resultat, undefined);
  assert.equal(this.erreur?.message, message);
});

Dans les définitions complètes, un Before recrée un historique vide pour chaque scénario. Les fonctions ordinaires donnent accès au contexte du scénario par this. Les assertions comparent le résultat à l’attendu.

Depuis la racine du dossier, après l’installation décrite dans le README :

npm run test:bdd

Le kit doit exécuter quatre scénarios et 23 étapes. Il écrit un rapport HTML local, sans utiliser le service de publication de Cucumber. Le contrôle qui suit refuse aussi une exécution avec zéro scénario. Consulte les scénarios réellement exécutés, les étapes ignorées et les éventuels échecs.

Ces tests portent sur les règles en mémoire. Ils ne vérifient pas l’authentification, un serveur, les courriels ou les accès simultanés à une base.

Générer ce que l’on sait extraire

La documentation peut aussi être consultée directement dans l’éditeur. Le guide JSDoc, TSDoc, TypeDoc et aide au survol montre comment faire apparaître le contrat d’une fonction pendant son utilisation, puis générer une référence à partir de ses commentaires. Les types, les explications et les tests se complètent.

Les commentaires JSDoc précisent les paramètres, les effets et les erreurs de la fonction. La commande suivante produit leur référence HTML :

npm run docs:api

JSDoc extrait les annotations et la structure qu’il sait analyser. Il ne prouve pas que chaque phrase du commentaire est correcte. La prose d’un commentaire peut rester fausse malgré une référence fraîchement générée.

Pour extraire les dépendances JavaScript :

npm run docs:deps

flowchart LR
    accDescr: Les imports de la démonstration relient le programme de lancement aux réservations, puis aux statuts.

subgraph 0["demo"]
subgraph 1["src"]
2["demo.mjs"]
3["reservations.mjs"]
4["statuts.mjs"]
end
end
2-->3
3-->4

Ce schéma provient de dependency-cruiser. Il représente des imports, pas l’ordre des appels ni l’architecture métier complète. Les noms de fichiers peuvent aider les développeurs, tandis qu’une personne du support aura plutôt besoin de la règle et d’un exemple.

Distinguer un diagramme textuel d’un diagramme extrait

Un fichier Mermaid écrit à la main décrit un modèle. Son texte se relit dans Git et son image se régénère. Pour suivre le logiciel, il faut encore actualiser ce modèle ou le comparer au code.

Un outil d’analyse peut extraire les imports du code ou les relations d’une base. Cela réduit certaines recopies, dans les limites de ce que l’outil observe. Une relation d’infrastructure ou une intention métier peut rester invisible.

Conserve les vues C4 pour donner le contexte aux lecteurs. Utilise les vues extraites pour explorer les détails techniques. La sélection d’outils compare Mermaid, Structurizr, LikeC4, dependency-cruiser, Mocodo et SchemaSpy.

Construire des pages accessibles aux collègues

MkDocs transforme des fichiers Markdown en site navigable avec recherche. Les lecteurs peuvent consulter le résultat sans lire les fichiers dans Git. La publication peut rester interne. L’édition peut passer par une proposition de changement accompagnée ou par l’interface du dépôt.

Pour inclure du code, commence par un outil existant comme JSDoc, TypeDoc ou un gestionnaire mkdocstrings adapté au langage. Les hooks de MkDocs permettent aussi de brancher une petite transformation spécifique, sans distribuer un plugin complet.

Le hook fourni insère des fichiers explicitement sélectionnés dans les pages, au moment de la construction. Les exemples complets l’utilisent. Il n’analyse pas les annotations JavaScript : JSDoc s’en charge séparément. Il ne parcourt pas aveuglément le disque.

Avant une extraction, choisis le public et les sources. Un fichier de configuration confidentiel, une donnée de test réelle ou un commentaire interne n’a pas automatiquement sa place dans une documentation partagée. Le script de préparation du site copie une liste précise de contenus pédagogiques.

Concevoir en écrivant la documentation

La documentation-driven design consiste à rédiger un usage, une explication ou un contrat avant de l’implémenter, puis à le faire relire. L’effort d’explication fait apparaître les ambiguïtés. Cette idée figure dans les principes de Write the Docs.

Avant de coder une réactivation, écris : “Une personne peut réactiver sa réservation annulée si une place est disponible.” La phrase ouvre déjà plusieurs questions : garde-t-on le même identifiant ? Qui peut réactiver ? Que répondre si l’atelier est complet ?

Discute ces questions, écris deux exemples et indique que le comportement est proposé. Implémente ensuite les exemples convenus et mets le statut de la documentation à jour.

Cette démarche complète la documentation extraite du code. L’une aide à concevoir un comportement, l’autre à consulter ce qui est décrit ou réalisé. Évite l’acronyme DDD sans précision : il désigne aussi le Domain-Driven Design, une autre approche centrée sur le domaine métier.

Exercice : faire évoluer une règle

1. Décidez si une réservation annulée devrait pouvoir être réactivée.
2. Écrivez un exemple accepté, un exemple refusé et une question non résolue.
3. Décidez si cette modification nécessite un nouvel ADR. Conservez le précédent comme trace historique.
4. Ajoutez le scénario avant de modifier le code. Constatez son échec ou son absence de définition.
5. Implémentez le comportement convenu dans une copie du kit.
6. Relancez les tests, générez la documentation et faites expliquer la règle par une personne qui n’a pas écrit le code.

Le corrigé dépend de la règle choisie. Pour observer une régression plus courte, lance npm run demo:regression dans le kit : la commande prépare une copie temporaire et vérifie que les tests détectent un dépassement de capacité.

À discuter : quelle information de ton projet peut être extraite automatiquement, et quelle information doit encore être expliquée par une personne ?

Retour au sommaire

Réserve ta place : démonstration des règles métier

Cette démonstration JavaScript permet de réserver et d’annuler une place à une séance de poterie. Elle sert à apprendre les tests comme documentation, Gherkin, JSDoc et la génération de diagrammes.

Elle fonctionne en mémoire pendant une exécution. Elle ne fournit ni site de réservation, ni API HTTP, ni base PostgreSQL. L’architecture web du cours est un exemple de conception distinct. Les identifiants sont fictifs et aucun compte n’est nécessaire.

Préparer le dossier

Ouvre un terminal à la racine du cours, le dossier contenant package.json. Toutes les commandes de cette page s’exécutent à cet endroit, même si ce README est dans demo.

Le kit cible Node.js 24 et Python 3.12 pour les outils de documentation. Vérifie :

node --version
python3 --version

Pour les deux premières commandes de démonstration, Node suffit. Aucun téléchargement de dépendance n’est nécessaire :

npm run demo
npm test

La démonstration affiche :

Réservation créée : confirmee
Après annulation : annulee
Nouvelle demande : Réservation déjà existante

La suite native doit exécuter six tests. Elle contrôle les places, les annulations, les doublons, l’indépendance des ateliers et quelques demandes invalides.

Installer les outils de documentation et BDD

Une connexion Internet est nécessaire pour la première installation. Les versions JavaScript sont enregistrées dans package-lock.json.

npm ci
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-docs.txt

Sous Windows, utilise .venv\Scripts\python à la place de .venv/bin/python. Les scripts de diagrammes fournis ont été vérifiés sous macOS, pas sous Windows.

Mermaid CLI utilise un navigateur Chromium pour exporter les images. Avec Helium déjà installé sur macOS, tu peux éviter le téléchargement d’un autre navigateur :

PUPPETEER_SKIP_DOWNLOAD=true npm ci
export PUPPETEER_EXECUTABLE_PATH="/Applications/Helium.app/Contents/MacOS/Helium"

Choisis l’une des deux méthodes d’installation npm. Si tu as désactivé le téléchargement, fournis ensuite le chemin du navigateur pour la génération des diagrammes.

Exécuter les scénarios métier

npm run test:bdd

Attendu : quatre scénarios et 23 étapes réussis. Le rapport est écrit dans .build/bdd.html. Les étapes invoquent les mêmes fonctions que les tests natifs.

Le format JSON est utilisé ici pour un petit contrôle de présence des scénarios. Cucumber le maintient pour compatibilité. Pour une nouvelle intégration de rapports plus poussée, étudie son format Messages.

Voir une régression détectée

npm run demo:regression

Le script travaille dans une copie temporaire. Il remplace le refus lorsque le nombre de places occupées est supérieur ou égal à la capacité par un refus seulement au-delà de la capacité. Deux tests doivent échouer, puis le script confirme que cette régression a été détectée.

La commande globale réussit lorsque l’échec attendu a été observé. Elle ne modifie pas les sources du cours et supprime uniquement la copie temporaire qu’elle vient de créer.

Construire la documentation

npm test
npm run test:bdd
npm run docs:api
npm run docs:deps
npm run docs:diagrams
.venv/bin/python -m mocodo --input cours-documentation/visuels/reservations.mcd --output_dir cours-documentation/visuels --colors brewer+1 --shapes arial
npm run check:links
.venv/bin/python scripts/preparer-site.py
.venv/bin/python -m mkdocs build --strict

Les schémas SVG livrés permettent de lire le cours sans installer le moteur de rendu. Pour une démonstration de génération, exécute toute la séquence ci-dessus. Une commande en échec doit être corrigée avant de passer à la suivante.

Ouvre le site local :

.venv/bin/python -m http.server 8000 --bind 127.0.0.1 --directory site

Dans le navigateur, ouvre le parcours local. Le menu Pratiquer mène aux résultats BDD et à la référence JSDoc. Arrête le serveur avec Ctrl+C.

Après une modification du code ou des sources documentaires, reconstruis les contenus concernés et le site. Le dossier .build/docs est une copie de construction. Modifie les fichiers originaux, jamais cette copie.

Retrouver les fichiers

Le prolongement JSDoc, TSDoc et TypeDoc explique le survol dans VS Code. Son exemple JavaScript se lance avec node demo/editeur/survol.js depuis la racine et affiche confirmee. La vérification des types et la génération TypeDoc sont des étapes optionnelles décrites dans ce prolongement.

Dépanner

Limites de la démonstration

La capacité est transmise par l’appelant pour raccourcir le code. Dans une application, elle viendrait d’un stockage maîtrisé par le serveur. L’historique est supposé interne et valide. Les fonctions ne constituent pas une frontière HTTP sécurisée. La réservation et l’annulation ne simulent pas plusieurs processus ni une transaction en base.

Signale un problème avec la commande, le résultat observé et la version de Node. Pour proposer une modification, actualise la règle, ses exemples et les tests concernés.

Exemples, fichiers exécutables et corrigés

Compare ton travail avec ces exemples et corrigés. Ils concernent Réserve ta place. Pour les adapter à un autre projet, vérifie ses règles.

1. Une réponse utile au support

Question : “Alice a annulé, il reste une place, pourquoi ne peut-elle pas réserver ?”

Réponse : “L’annulation libère la place, mais conserve sa réservation. Le service refuse une nouvelle création pour la même personne et la même séance. Une autre personne peut prendre la place.”

Retrouve l’exemple refusé dans les scénarios, puis sa raison dans l’ADR. Si la réponse n’est pas acceptable pour le métier, note une demande d’évolution.

2. Un classement Diátaxis

Le classement porte sur l’intention de la page. Une FAQ mêlant toutes ces intentions gagnera souvent à renvoyer vers des pages ciblées.

3. Une règle précise

Remplace “les annulations sont bien gérées” par “une annulation conserve la réservation et libère sa place. Répéter l’annulation conserve le statut annulé.”

Pour vérifier la seconde phrase, ajoute un test qui appelle deux fois annuler sur la même réservation.

4. Une procédure vérifiable

Le README complet est le document à essayer. Une autre personne doit retrouver le dossier de départ, les prérequis et le résultat attendu sans explication supplémentaire.

Le programme principal doit afficher successivement une réservation confirmée, une réservation annulée et le refus d’une nouvelle création.

5. Une architecture lisible

La vue de contexte permet à une personne extérieure de nommer les utilisateurs et le service de courriel. La vue de conteneurs distingue le navigateur, le serveur et PostgreSQL. Ce sont des modèles de l’application fictive, pas une découverte automatique du kit.

Source utilisée pour la vue de contexte, incluse automatiquement dans le site :

C4Context
    title Réserve ta place : contexte du système fictif
    Person(participant, "Participant", "Réserve une place")
    Person(organisateur, "Organisateur", "Publie les ateliers")
    System(reservations, "Réserve ta place", "Gère les ateliers et les réservations")
    System_Ext(courriels, "Service de courriels", "Envoie les confirmations")
    Rel(participant, reservations, "Consulte et réserve")
    Rel(organisateur, reservations, "Publie et consulte")
    Rel(reservations, courriels, "Demande un envoi")
    UpdateRelStyle(reservations, courriels, $offsetX="-45", $offsetY="-65")
    UpdateLayoutConfig($c4ShapeInRow="2", $c4BoundaryInRow="1")

En lecture Markdown directe, ouvrir le fichier source.

6. Du MCD au modèle relationnel

Une Personne peut n’avoir aucune réservation. Une Réservation concerne exactement une Personne et un Atelier. Le couple personne-atelier doit être unique selon la règle retenue.

Personne: id personne, nom
Effectuer, 0N Personne, 11 Réservation
Réservation: id réservation, date création, statut
Concerner, 11 Réservation, 0N Atelier
Atelier: id atelier, titre, date atelier, capacité

Fichier Mocodo.

erDiagram
    Personnes ||--o{ Reservations : effectue
    Ateliers ||--o{ Reservations : concerne
    Personnes {
      int id PK
      string nom
    }
    Ateliers {
      int id PK
      string titre
      datetime date_atelier
      int capacite
    }
    Reservations {
      int id PK
      datetime date_creation
      string statut
      int personne_id FK
      int atelier_id FK
    }

Fichier Mermaid ER.

Les clés étrangères matérialisent les liens. La règle d’unicité du couple demande une contrainte supplémentaire. Dans l’exercice Bibi d’objets, deux emprunts successifs du même objet par la même personne doivent au contraire rester possibles.

7. Une décision, un commentaire et une implémentation

L’ADR rempli décrit les options et la restriction choisie. Voici l’implémentation et ses annotations, extraites du fichier réellement exécuté lors de la construction du site :

import { CONFIRMEE, ANNULEE } from './statuts.mjs';

/** Règles de réservation de la démonstration en mémoire. @module reservations */

/**
 * @typedef {Object} Reservation
 * @property {string} personne Identifiant fictif de la personne.
 * @property {string} atelier Identifiant fictif de la séance.
 * @property {'confirmee'|'annulee'} statut Une annulation conserve la réservation.
 */

/**
 * Réserve une place et conserve la réservation dans la liste reçue.
 * Une seconde réservation reste interdite après annulation.
 * @param {Reservation[]} reservations Historique partagé pendant un scénario.
 * @param {Object} demande Identifiants et capacité de la séance.
 * @param {string} demande.personne Identifiant non vide.
 * @param {string} demande.atelier Identifiant non vide.
 * @param {number} demande.capacite Nombre entier de places, supérieur ou égal à zéro.
 * @returns {Reservation} La réservation créée.
 * @throws {Error} Demande invalide, réservation déjà existante ou atelier complet.
 * @example
 * reserver([], { personne: 'alice', atelier: 'poterie', capacite: 1 });
 */
export function reserver(reservations, { personne, atelier, capacite }) {
  if (
    typeof personne !== 'string' || !personne.trim() ||
    typeof atelier !== 'string' || !atelier.trim() ||
    !Number.isSafeInteger(capacite) || capacite < 0
  ) {
    throw new Error('Demande invalide');
  }

  if (reservations.some(r => r.personne === personne && r.atelier === atelier)) {
    throw new Error('Réservation déjà existante');
  }

  const occupees = reservations.filter(
    r => r.atelier === atelier && r.statut === CONFIRMEE
  ).length;
  if (occupees >= capacite) {
    throw new Error('Atelier complet');
  }

  const reservation = { personne, atelier, statut: CONFIRMEE };
  reservations.push(reservation);
  return reservation;
}

/**
 * Libère une place en conservant la réservation dans l'historique.
 * Répéter l'annulation ne crée pas de nouvelle modification métier.
 * @param {Reservation} reservation Réservation issue de cette démonstration.
 * @returns {void}
 */
export function annuler(reservation) {
  reservation.statut = ANNULEE;
}

Fichier JavaScript. JSDoc génère en parallèle une référence navigable. L’inclusion ci-dessus montre le fichier complet, elle n’analyse pas les annotations.

8. Des tests qui vérifient les effets

Les tests vérifient les réservations créées, les refus et l’absence d’ajout lorsque la demande échoue.

import test from 'node:test';
import assert from 'node:assert/strict';
import { reserver, annuler } from '../src/reservations.mjs';

test('la dernière place peut être réservée, la demande suivante est refusée', () => {
  const historique = [];
  assert.equal(reserver(historique, {
    personne: 'alice', atelier: 'poterie', capacite: 1
  }).statut, 'confirmee');
  assert.throws(() => reserver(historique, {
    personne: 'bob', atelier: 'poterie', capacite: 1
  }), { message: 'Atelier complet' });
  assert.equal(historique.length, 1);
});

test('une annulation libère la place pour une autre personne', () => {
  const historique = [];
  annuler(reserver(historique, {
    personne: 'alice', atelier: 'poterie', capacite: 1
  }));
  reserver(historique, { personne: 'bob', atelier: 'poterie', capacite: 1 });
  assert.deepEqual(historique.map(r => r.statut), ['annulee', 'confirmee']);
});

test('une même personne ne peut pas réserver à nouveau après annulation', () => {
  const historique = [];
  annuler(reserver(historique, {
    personne: 'alice', atelier: 'poterie', capacite: 1
  }));
  assert.throws(() => reserver(historique, {
    personne: 'alice', atelier: 'poterie', capacite: 1
  }), { message: 'Réservation déjà existante' });
  assert.equal(historique.length, 1);
});

test('les ateliers possèdent des capacités indépendantes', () => {
  const historique = [];
  reserver(historique, { personne: 'alice', atelier: 'poterie', capacite: 1 });
  reserver(historique, { personne: 'alice', atelier: 'dessin', capacite: 1 });
  assert.equal(historique.length, 2);
});

test('une capacité nulle refuse la première réservation', () => {
  assert.throws(() => reserver([], {
    personne: 'alice', atelier: 'poterie', capacite: 0
  }), { message: 'Atelier complet' });
});

test('une demande invalide ne modifie pas l’historique', () => {
  for (const demande of [
    { personne: '', atelier: 'poterie', capacite: 1 },
    { personne: 'alice', atelier: '', capacite: 1 },
    { personne: 'alice', atelier: 'poterie', capacite: -1 },
    { personne: 'alice', atelier: 'poterie', capacite: 1.5 }
  ]) {
    const historique = [];
    assert.throws(() => reserver(historique, demande), { message: 'Demande invalide' });
    assert.equal(historique.length, 0);
  }
});

Fichier de tests.

La démonstration npm run demo:regression modifie une copie temporaire. Deux tests échouent, car le contrôle de capacité accepte à tort une demande lorsque toutes les places sont déjà prises.

9. Un scénario relié au code

# language: fr
Fonctionnalité: Réserver une place à un atelier
  Les participants peuvent réserver une place disponible.
  L'association conserve les annulations et interdit une seconde réservation
  pour la même personne et la même séance, même après annulation.

  Scénario: Réserver la dernière place
    Étant donné un atelier de 1 place
    Quand Alice réserve une place
    Alors sa réservation est confirmée
    Et l'historique contient 1 réservation

  Scénario: Refuser une réservation lorsque l'atelier est complet
    Étant donné un atelier de 1 place
    Et Bob possède une réservation confirmée
    Quand Alice réserve une place
    Alors la demande est refusée avec "Atelier complet"
    Et l'historique contient 1 réservation

  Scénario: Conserver l'interdiction de réserver à nouveau après annulation
    Étant donné un atelier de 1 place
    Et Alice possède une réservation annulée
    Quand Alice réserve une place
    Alors la demande est refusée avec "Réservation déjà existante"
    Et l'historique contient 1 réservation

  Scénario: Libérer la place pour une autre personne
    Étant donné un atelier de 1 place
    Et Bob possède une réservation annulée
    Quand Alice réserve une place
    Alors sa réservation est confirmée
    Et l'historique contient 2 réservations

Fichier Gherkin.

import { Before, Given, When, Then } from '@cucumber/cucumber';
import assert from 'node:assert/strict';
import { reserver, annuler } from '../../src/reservations.mjs';

Before(function () {
  this.historique = [];
  this.resultat = undefined;
  this.erreur = undefined;
});

Given('un atelier de {int} place', function (capacite) {
  this.capacite = capacite;
});

Given(/^(Alice|Bob) possède une réservation (confirmée|annulée)$/, function (personne, statut) {
  const reservation = reserver(this.historique, {
    personne, atelier: 'poterie', capacite: this.capacite
  });
  if (statut === 'annulée') annuler(reservation);
});

When('Alice réserve une place', function () {
  try {
    this.resultat = reserver(this.historique, {
      personne: 'Alice', atelier: 'poterie', capacite: this.capacite
    });
  } catch (erreur) {
    this.erreur = erreur;
  }
});

Then('sa réservation est confirmée', function () {
  assert.equal(this.erreur, undefined);
  assert.equal(this.resultat?.statut, 'confirmee');
});

Then('la demande est refusée avec {string}', function (message) {
  assert.equal(this.resultat, undefined);
  assert.equal(this.erreur?.message, message);
});

Then("l'historique contient {int} réservation(s)", function (nombre) {
  assert.equal(this.historique.length, nombre);
});

Définitions d’étapes.

La fonction appelée par l’étape est celle utilisée dans le programme. Une assertion indépendante compare son résultat à l’attendu. Le scénario prépare son propre état, afin de pouvoir s’exécuter sans dépendre du précédent.

Inclure des sources dans MkDocs

Le hook ci-dessous traite uniquement des marqueurs explicites et des chemins autorisés. Pour voir son effet, construire le site et ouvrir cette page. Une source absente ou un chemin non autorisé fait échouer la construction.

"""Inclure des exemples explicitement choisis dans la documentation de l'atelier."""
from pathlib import Path
import re

ROOT = Path(__file__).resolve().parents[1]
SOURCES = {
    "demo/editeur/survol.js": "javascript",
    "demo/editeur/capacite.ts": "typescript",
    "demo/src/reservations.mjs": "javascript",
    "demo/features/reservations.feature": "gherkin",
    "demo/features/steps/reservations.mjs": "javascript",
    "demo/tests/reservations.test.mjs": "javascript",
    "cours-documentation/visuels/c4-contexte.mmd": "text",
    "cours-documentation/visuels/reservations.mcd": "text",
    "cours-documentation/visuels/reservations-erd.mmd": "text",
    "cours-documentation/visuels/adr-annulation.mmd": "text",
    "scripts/mkdocs_hook.py": "python",
}


def on_page_markdown(markdown, **kwargs):
    def include(match):
        name = match.group(1)
        if name not in SOURCES:
            raise ValueError("Source non autorisée pour la documentation : " + name)
        content = (ROOT / name).read_text(encoding="utf-8")
        return "\n~~~" + SOURCES[name] + "\n" + content + "\n~~~\n"

    return re.sub(r"<!-- inclure: ([\w/.-]+) -->", include, markdown)

Fichier du hook.

Ce petit mécanisme convient à quelques exemples pédagogiques choisis. Une extraction de signatures ou de commentaires de tout un langage demande un analyseur existant, comme JSDoc, TypeDoc ou un gestionnaire mkdocstrings.

Documenter une fonction jusque dans l’éditeur

Les commentaires placés près du code peuvent alimenter l’aide au survol, l’assistance à la saisie et une référence publiée. Cette manipulation prolonge les chapitres Décisions et code et Documentation vivante.

Distinguer les rôles

Sources : JSDoc, TSDoc, TypeDoc et prise en charge JavaScript dans VS Code.

TSDoc ne remplace pas les types TypeScript. Dans un fichier TypeScript, les types sont écrits dans les signatures ou inférés par l’analyseur. Les commentaires expliquent les unités, les effets, les préconditions et les raisons qu’une signature ne suffit pas à transmettre.

Obtenir le survol en JavaScript

1. Ouvrir le dossier du cours dans VS Code.
2. Ouvrir demo/editeur/survol.js.
3. Survoler le nom reserver dans l’appel. L’éditeur doit présenter la signature et la description issues du fichier documenté.
4. Survoler reservation.statut : le type attendu est l’union des valeurs confirmee et annulee.
5. Placer le curseur dans l’appel pour consulter l’aide sur les paramètres.

Sur macOS, le raccourci du survol est Commande+K puis Commande+I. Sous Windows et Linux, c’est Ctrl+K puis Ctrl+I. L’aide à la signature se déclenche avec Commande+Maj+Espace sur macOS, Ctrl+Maj+Espace ailleurs. Référence VS Code.

Le fichier utilisé est inclus ci-dessous au moment de construire le site :

// @ts-check
import { reserver } from '../src/reservations.mjs';

/** @type {import('../src/reservations.mjs').Reservation[]} */
const historique = [];

const reservation = reserver(historique, {
  personne: 'alice',
  atelier: 'poterie',
  capacite: 3
});

console.log(reservation.statut);

L’annotation @type décrit ici la liste avant qu’elle contienne une réservation. @param, @returns et @typedef dans le fichier importé fournissent les autres informations. Un commentaire de documentation commence par /** et se place devant la déclaration concernée. La référence TypeScript sur JSDoc précise les annotations reconnues par son analyseur.

Lancer cet exemple depuis la racine avec :

node demo/editeur/survol.js

Résultat attendu : confirmee.

Faire signaler un mauvais type

Dans une copie de survol.js, remplacer la valeur numérique de capacite par le texte ‘trois’. La ligne // @ts-check active la vérification de ce fichier JavaScript. L’éditeur doit signaler qu’une chaîne de caractères n’est pas assignable à un nombre. Corriger ensuite la valeur.

Le tsconfig de l’exercice autorise l’analyse du JavaScript et n’émet pas de nouveaux fichiers. Il limite les fichiers d’entrée aux deux exemples. Les modules importés sont aussi lus pour connaître leurs signatures. Il ne lance pas une vérification exhaustive du kit.

Le survol et la complétion peuvent fonctionner sans @ts-check. Cette directive ajoute des diagnostics sur le JavaScript. Pour étendre la vérification à un projet, examiner l’option checkJs dans sa configuration existante. TypeScript dans les projets JavaScript.

Un type number n’impose pas un entier positif. Le contrôle de types ne remplace pas la validation des données à l’exécution. Une valeur provenant d’un formulaire ou d’une réponse réseau reste à valider.

Écrire la variante TypeScript avec des commentaires TSDoc

L’exemple suivant est une fonction d’affichage indépendante. Elle ne réalise pas une réservation.

/**
 * Calcule le nombre de places encore disponibles pour l’affichage.
 *
 * @remarks
 * Les arguments sont supposés être des entiers positifs ou nuls déjà validés.
 * Cette fonction ne réserve aucune place et ne contrôle pas les accès concurrents.
 *
 * @param capacite - Nombre total de places de la séance.
 * @param confirmees - Nombre de réservations qui occupent une place.
 * @returns Le nombre de places restantes, ramené à zéro si la capacité est dépassée.
 * @example
 * placesRestantes(8, 6) // 2
 */
export function placesRestantes(capacite: number, confirmees: number): number {
  return Math.max(0, capacite - confirmees);
}

Fichier TypeScript complet.

Les types number sont dans la signature. La forme @param capacite - Description explique le paramètre sans recopier son type entre accolades. @remarks détaille les limites, @returns le résultat et @example un usage.

TypeDoc s’appuie sur une syntaxe inspirée de TSDoc, avec des différences et extensions documentées. Ne suppose pas que chaque balise sera rendue de façon identique dans l’éditeur, JSDoc et TypeDoc. Commentaires reconnus par TypeDoc.

Vérifier les types puis générer une référence TypeDoc

Ces commandes constituent un prolongement optionnel. Les outils de base du kit restent suffisants pour le reste du cours. Depuis la racine, dans une copie de travail, installer les versions utilisées pour vérifier cet exemple :

npm install --save-dev --save-exact typescript@6.0.3 typedoc@0.28.20
npx tsc -p demo/editeur/tsconfig.json
npx typedoc demo/editeur/capacite.ts --tsconfig demo/editeur/tsconfig.json --out .build/typedoc

Le contrôle doit terminer sans diagnostic. La référence se trouve dans .build/typedoc/index.html. Lancer un serveur local pour la consulter :

python3 -m http.server 8001 --bind 127.0.0.1 --directory .build/typedoc

Ouvrir ensuite la référence TypeDoc locale. Retrouver placesRestantes, ses paramètres et son exemple. Ce serveur est distinct de celui du cours sur le port 8000.

VS Code fournit son service de langage, mais l’installation de TypeScript dans le projet fournit la commande tsc. Pour comparer des diagnostics qui diffèrent, vérifier la version TypeScript choisie par l’éditeur. Tutoriel TypeScript de VS Code.

Relier cette aide à la documentation vivante

Modifier la description d’une fonction, enregistrer et consulter son aide au survol. Reconstruire ensuite la référence publiée. Le commentaire reste près du code et sert à plusieurs lecteurs.

La génération ne prouve pas l’exactitude des phrases. Un bloc @example n’est pas automatiquement un test exécuté par TypeDoc ou JSDoc. Si cet exemple exprime une règle importante, vérifier son résultat avec un test ou un scénario adapté.

Documenter en priorité les points d’entrée utilisés par d’autres personnes, les effets et les limites. Pour un collègue du support, publier aussi les règles en langage métier et leurs exemples. Le survol aide surtout la personne qui travaille dans le code.

Exercice : vérifier un contrat dans l’éditeur

Choisis une fonction dont le contrat manque de précision. Écris le commentaire, puis utilise la fonction depuis un second fichier.

Vérifier que le survol explique le résultat et les effets. Passer volontairement une valeur du mauvais type et lire le diagnostic. Corriger l’appel, puis expliquer une contrainte que le type ne peut pas garantir, par exemple “capacité entière et positive ou nulle”.

Si rien ne s’affiche, vérifier le mode de langage du fichier, le réglage editor.hover.enabled et l’activation de la prise en charge intégrée JavaScript/TypeScript. Le commentaire doit être attaché à la déclaration ou à la propriété concernée. Un générateur HTML installé ne répare pas à lui seul un service de langage désactivé.

ADR 001 : conserver les réservations annulées

Date : 10 septembre 2026. Statut : accepté pour la démonstration pédagogique. Portée : règles de réservation du kit en mémoire, sans base de données déployée.

Contexte

L’association fictive veut retrouver qu’une personne a déjà réservé une séance, même après annulation. Une personne peut réserver plusieurs séances, mais une seule réservation par couple personne-séance est conservée. Le kit doit rendre cette règle observable avec quelques exemples.

La conservation d’un enregistrement avec son statut courant permet de retrouver une annulation. Elle ne constitue pas un journal complet de tous les changements.

Options examinées

Décision

L’annulation remplace le statut confirmé par annulé et conserve la réservation dans la liste. Seules les réservations confirmées occupent une place. Une seconde création pour le même couple personne-séance est refusée, quel que soit le statut de la précédente.

stateDiagram-v2
    accDescr: États du modèle retenu à la date de la décision.
    [*] --> Confirmée : place attribuée
    Confirmée --> Annulée : annulation
    note right of Annulée
      La réservation reste dans l'historique.
      Une nouvelle création pour le même couple
      personne / atelier est refusée.
      La réactivation n'est pas proposée dans la démo.
    end note

Source Mermaid de cet état historique.

Conséquences

Une place annulée devient disponible pour une autre personne. La personne qui a annulé ne peut pas revenir par une nouvelle création. Cette restriction doit apparaître dans l’aide et dans le message expliqué par le support.

Une demande future de réactivation devra préciser la disponibilité, les permissions et le maintien de l’identifiant. Si elle est acceptée, une nouvelle décision remplacera celle-ci. Cet ADR gardera la trace du choix initial.

Dans une application persistante, il faudra définir la durée de conservation, la suppression des données personnelles et les contraintes de base appropriées. Le kit ne choisit pas de politique de conservation réelle et n’implémente aucune migration SQL.

Vérifier le choix

• Scénarios métier : refus après annulation et place libérée pour une autre personne.
• Tests de la règle.
• Implémentation et annotations.

Lancer npm test et npm run test:bdd depuis la racine du kit. Les tests rendent observable le comportement retenu. Leur réussite ne décide pas si la restriction convient encore aux utilisateurs.

Choisir les outils et vérifier les sources

Sources consultées les 9 et 10 septembre 2026. Les versions du kit sont fixées pour reproduire la démonstration. Les outils cités comme alternatives demandent un essai sur le langage et le projet de l’équipe.

Commencer avec une chaîne courte

Le kit utilise des fichiers Markdown, des sources Mermaid ou Mocodo, des tests et des commentaires JavaScript. MkDocs rassemble les pages, le rapport BDD et la référence générée dans un site avec recherche.

Pour un premier projet, choisir une règle métier, un ADR et une vue d’architecture. Automatiser leur vérification ou leur génération quand l’entrée est clairement identifiée. Éviter de commencer par un plugin censé comprendre tous les fichiers du dépôt.

Ce que chaque outil produit

Pour une API HTTP, OpenAPI décrit un contrat. Choisir une stratégie explicite : contrat écrit d’abord ou contrat extrait du serveur. Vérifier les exemples contre l’implémentation. Le kit n’inclut pas de serveur HTTP et ne prétend pas valider un contrat OpenAPI.

Versions utilisées dans la démonstration

Le prolongement sur la documentation dans l’éditeur fournit les exemples JavaScript et TypeScript, les raccourcis de survol et les commandes de génération TypeDoc. Ses outils optionnels sont séparés des dépendances du kit de base.

Le verrou npm conserve les versions des dépendances JavaScript. Le fichier requirements-docs.txt fixe les deux outils Python principaux, sans verrouiller toutes leurs dépendances transitives. Le rendu local a été préparé avec Helium sur macOS. Le README explique la configuration du navigateur.

Inclure des fichiers ou écrire un plugin MkDocs

Un hook MkDocs suffit pour la transformation spécifique du kit. Il reconnaît des marqueurs d’inclusion et lit les fichiers autorisés. La référence des annotations JavaScript est produite séparément par JSDoc.

Un plugin MkDocs complet devient utile lorsque cette logique doit être empaquetée, configurée et partagée entre plusieurs projets. Avant de l’écrire, vérifier si un générateur ou un gestionnaire de langage couvre déjà le besoin. Extraire tous les commentaires sans sélection produirait aussi des notes internes, des détails inutiles et des textes potentiellement périmés.

Conférence Living Documentation

La vidéo indiquée par Samuel Rozé correspond au sujet présenté au Forum PHP 2020. Le diaporama et les captures fournies montrent les exemples cités ici.

Trois idées sont mises en pratique dans le kit : relier des scénarios au comportement, conserver les décisions dans le dépôt et publier une documentation que d’autres métiers peuvent consulter. La capture suivante montre le résultat présenté dans la conférence, pas une interface fournie par ce kit.

Crédits de la capture.

Le chiffre de 40 à 60 % visible sur une autre diapositive n’est pas repris comme fait établi : la source primaire et sa méthode n’ont pas été vérifiées. De même, les noms d’outils d’une conférence de 2020 doivent être recontrôlés avant installation.

Retour d’expérience sur les agents IA

Dans Our top code contributor is an AI agent: our learnings so far, publié le 14 septembre 2025, Samuel Rozé décrit l’importance des tests exécutables, du retour conservé dans les consignes et de la préparation technique des tâches. Il présente une expérience d’équipe, sans démontrer une supériorité générale des agents.

Application au cours : donner à un collègue ou à un agent des exemples, les décisions applicables et une procédure de vérification. Relire les changements et mesurer les défauts ou le temps de reprise. Le nombre de contributions ne mesure pas à lui seul la qualité.

Un plan de réalisation et un ADR peuvent se compléter. Le premier organise des tâches, le second conserve une décision et ses conséquences. Une documentation générée par une IA demande aussi de vérifier les faits, les liens et le comportement décrit.

Lectures par chapitre

L’exercice sur les emprunts successifs part du dictionnaire de Bibi d’objets. Les règles complémentaires proposées au chapitre 6 restent à confirmer avec le métier.

Crédits et sources des visuels

Vérification des sources : 9 et 10 septembre 2026. Les photos montrent des situations réelles. L’application Réserve ta place et ses règles sont fictives.

Photographies

La photo des notes sert d’illustration d’un atelier de discussion. Elle ne documente pas une séance BDD. Conserver les attributions et les liens de licence avec les images.

Captures de la conférence

Les trois captures ont été fournies pour ce cours :

• Scénarios BDD.
• Mermaid dans un ADR.
• Documentation publiée.

Source : Samuel Rozé, Living Documentation, 2020. Vidéo indiquée, diaporama retrouvé.

Ces captures ne sont pas placées sous les licences Creative Commons des photos. Leur présence ici ne vaut pas attribution d’une licence de redistribution générale. Les explications du cours sont reformulées et les exemples exécutables ont été créés pour ce cours.

Schémas du cours

Les SVG sont générés depuis les fichiers Mermaid voisins, ou depuis reservations.mcd pour le MCD. Les formes et textes expliquent le cas pédagogique. Les méthodes utilisées sont attribuées dans les chapitres : Diátaxis, C4, Merise et Example Mapping.

Le graphe dependances.svg provient des imports réels du kit, extraits avec dependency-cruiser. Les vues C4 et la séquence décrivent une application fictive plus large. Le diagramme adr-annulation conserve l’état retenu par l’ADR 001.

Pour modifier une illustration, éditer sa source textuelle puis suivre les commandes du kit. Conserver ensemble le texte modifiable et le rendu que les lecteurs peuvent ouvrir.