Le cahier des charges, page par page, et le diagramme de classes

Temps 1 · séance 1 · ~20 min + maison

Les slides du chapitre (PDF)PDF

• Écrire les besoins de votre portfolio, chacun avec un critère d'acceptation.
• Distinguer les besoins obligatoires des bonus.
• Estimer en heures le temps que demande chaque besoin.
• Dessiner le diagramme de classes des données de votre portfolio.

1. Pourquoi écrire avant de coder#

Un cahier des charges est le document qui liste ce que le site doit faire, avant la première ligne de code. Chaque ligne décrit un besoin, une chose que le site doit permettre. Chaque besoin porte un critère d'acceptation, la vérification qui dit si le besoin est rempli.

Un besoin sans critère ne se vérifie pas. « L'accueil est clair » peut être vrai pour vous et faux pour un recruteur. « À 1280 px de large, le nom et le poste visé sont visibles sans défiler » se constate en ouvrant le site. Vous, un camarade ou le professeur arrivez à la même réponse.

Le cahier des charges contient aussi une estimation, le nombre d'heures que vous prévoyez pour chaque besoin. Pendant le projet, vous notez à côté le temps réellement passé, et à la remise vous expliquez l'écart le plus grand. Vous en écrirez un aussi pour l'examen.

2. Le gabarit, page par page#

Le gabarit du cahier des charges suit la structure dégagée à la mise en commun du chapitre 1.02. Il compte une section par page du site : l'accueil, les projets, la fiche d'un projet, l'à-propos, le contact, les mentions légales et le back-office. Une section « Toutes les pages » réunit ce qui vaut partout, comme les titres, l'accessibilité, les tests et la mise en ligne.

Téléchargez le cahier des charges en WordDOCX, que vous remplirez puis rendrez en PDF. La version PDFPDF sert à le lire.

En tête, le contexte décrit le site, ses lecteurs et le plan des adresses. En fin, le hors périmètre liste ce que le site ne fera pas, par exemple un blog ou plusieurs langues.

Chaque page reçoit le même traitement, en trois tableaux.

1. Ce que la page montre, et pour qui : le lecteur qui survole ou celui qui creuse, vus au chapitre 1.01.
2. Les besoins obligatoires, numérotés, chacun avec son critère d'acceptation.
3. Les bonus, numérotés et vérifiables de la même façon.

Le numéro reprend trois lettres de la page, et TRA pour ce qui vaut sur toutes les pages. ACC-1 est le premier besoin de l'accueil, CON-2 le deuxième du contact, ADM-B1 le premier bonus du back-office. Ce numéro sert de référence dans l'estimation, puis dans vos tests.

Un besoin bien écrit, un besoin mal écrit#

Voici le même besoin de la page de contact, écrit deux fois.

	Mal écrit	Bien écrit
Besoin	Le formulaire de contact fonctionne bien.	Un formulaire avec le nom, l'adresse e-mail et le message, validé par le serveur.
Critère	Le formulaire est facile à utiliser.	Envoyé vide, le formulaire affiche une erreur en français sous chaque champ. Une adresse e-mail mal formée est refusée.

La colonne de gauche repose sur des mots qui dépendent du lecteur, « bien » et « facile ». Personne ne peut les vérifier, et chacun peut les contester. La colonne de droite nomme les trois champs, décrit une action et dit ce qui doit apparaître à l'écran. Pour la vérifier, vous ouvrez /contact, vous envoyez le formulaire vide et vous regardez sous chaque champ.

Un critère se vérifie en ouvrant le site ou en lançant un test. Si vous ne savez pas comment vérifier un critère, réécrivez-le jusqu'à le savoir.

3. Le minimum noté et les bonus#

Le gabarit arrive pré-rempli. Les besoins déjà écrits forment le minimum noté du portfolio, la base de la grille de remise. Vous les gardez avec leur critère, sans les retirer ni les affaiblir. Ils couvrent dix points.

1. Le CRUD complet des projets derrière une connexion : créer, lire, modifier et supprimer un projet depuis le back-office.
2. Au moins trois projets publiés, chacun avec une image, un contenu en texte riche et ses liens.
3. Une page publique par projet, une page à propos et un formulaire de contact qui envoie un e-mail.
4. La direction artistique de votre planche, appliquée au site.
5. Un titre et une description sur chaque page publique, et les balises Open Graph sur chaque fiche de projet, qui donnent l'aperçu d'un lien partagé.
6. Les cinq vérifications d'accessibilité de base, listées dans le besoin TRA-3, et des mentions légales.
7. Cinq tests verts.
8. Le site en ligne chez OVH.
9. Un README qui permet d'installer le projet.
10. Le cahier des charges, avec l'estimé et le réel.

Le gabarit marque « [à adapter] » ce qui dépend de vous : la description du site, les lecteurs, l'accueil, l'à-propos et vos liens. Les lignes vides attendent vos propres besoins, chacun avec un critère.

Vos bonus sont les vôtres. Le gabarit en propose plusieurs, comme filtrer les projets par étiquette ou un mode sombre. Vous pouvez en choisir, en inventer ou n'en prendre aucun. Un bonus s'écrit avec un critère et s'estime comme un besoin obligatoire, mais il ne remplace jamais un point du minimum.

4. CV ou vitrine#

Le contexte contient votre décision entre le mode CV et la vitrine de projets, vue au chapitre 1.01. Vous cochez une case, puis vous justifiez votre choix en deux lignes. La justification part de votre situation, pas d'une règle générale.

Vitrine de projets. Mon métier d'avant n'a pas de lien avec le web. Mes projets montrent mieux ce que je sais faire, et le CV en PDF garde mon parcours.

Entre les deux. Mes dix ans en logistique intéressent les entreprises du secteur. L'à-propos reçoit une courte section « parcours », et les projets restent en tête de l'accueil.

En mode CV, l'à-propos s'allonge et le CV en PDF devient indispensable. En vitrine, l'accueil met davantage de projets en avant.

5. L'estimation#

La section « Estimation » reprend chaque besoin sur une ligne : numéro, nom, estimé en heures, réel et écart. Vous remplissez l'estimé à la maison, puis le total des besoins obligatoires et celui des bonus. Le réel et l'écart se remplissent pendant le projet.

Vous n'avez encore jamais construit de back-office avec Inertia. Comparez chaque besoin à ce que vous avez fait en 5XCOS, puis ajoutez du temps pour ce qui est nouveau. Une étudiante se souvient d'avoir passé environ deux heures sur le formulaire d'ajout du refuge, et raisonne ainsi.

N°	Besoin	Ce qu'elle compare	Estimé
CON-1	Formulaire validé	le formulaire du refuge, qu'elle connaît	2 h
CON-2	Message enregistré et envoyé	une table et un modèle connus, plus un e-mail qu'elle n'a jamais envoyé	3 h
ADM-4	Créer un projet	le formulaire du refuge, plus l'image et le texte riche, deux choses nouvelles, et les étiquettes vues en 5XCOS	6 h

Votre estimation sera fausse, surtout pour ce que vous n'avez jamais fait, et le plus souvent trop basse. L'écart entre l'estimé et le réel est ce que l'estimation vous apprend. À la remise, vous expliquez le plus grand en trois lignes, et votre prochaine estimation en tient compte. Un estimé gonflé ne vous apprend rien sur votre façon de travailler.

6. Le diagramme de classes#

Le cahier des charges dit ce que le site montre. Le diagramme de classes, que vous dessinez depuis 5XCOS, dit quelles données le site garde. Vous le dessinez vous-même, à partir de vos besoins, et il entre dans votre cahier des charges. Le chapitre 1.06 montrera celui du cours, et vous le comparerez au vôtre.

La méthode tient en quatre étapes.

1. Les classes. Relisez vos besoins obligatoires et soulignez les noms de ce qui s'enregistre en base : ce que le back-office crée, ce que le formulaire de contact garde, qui se connecte. Chaque nom souligné devient une classe. Le kit installé au chapitre 1.04 fournit déjà la classe de la connexion : ouvrez app/Models/User.php et reprenez ce que la connexion utilise, sans la réinventer.
2. Les attributs. Pour la classe des projets, partez de la fiche projet du chapitre 1.01. Plusieurs rubriques peuvent finir dans le même attribut : demandez-vous ce qui s'affiche séparément sur le site. Relisez vos besoins : lesquels demandent une information que la fiche ne contient pas ?
3. Les multiplicités. Un attribut qui peut manquer porte [0..1] : un projet sans démo en ligne, un dépôt resté privé, une image pas encore choisie.
4. Les relations. Pour chaque paire de classes, posez les deux questions : « un X a combien de Y ? » et « un Y a combien de X ? ». Écrivez les multiplicités aux deux bouts, les deux rôles et un verbe avec son sens de lecture, comme au festival de 5XCOS.

Votre diagramme est prêt quand :

• chaque besoin obligatoire qui enregistre quelque chose a sa classe
• chaque information de la fiche projet trouve sa place dans un attribut, avec son type
• chaque attribut qui peut manquer porte [0..1]
• chaque relation porte ses deux multiplicités, ses deux rôles et son verbe, dans la notation de 5XCOS
• aucune classe ni aucun trait ne reste sans besoin qui le justifie

Ce diagramme devient vos migrations à la séance 2, au chapitre 1.06 : une table par classe, et une table pivot pour chaque relation plusieurs à plusieurs. Dessinez-le d'abord sur papier, puis, si vous le souhaitez, dans Modelio, StarUML ou PlantUML. Le gabarit du cahier des charges a une place pour la photo de votre papier ou pour un bloc PlantUML.

7. Ce que vous faites maintenant et à la maison#

En séance, ouvrez le gabarit et commencez le contexte : la description du site, les lecteurs et le plan, recopié de la structure retenue par le groupe à la mise en commun du chapitre 1.02.

À la maison, écrivez la page d'accueil : ce qu'elle montre, pour qui, et ses besoins avec leur critère. Finissez ensuite le cahier des charges avec la collecte du devoir de la semaine, décrite au chapitre 1.01. Vos fiches complètent les pages des projets, vos informations sur vous complètent l'à-propos. Remplissez l'estimé de chaque besoin, comme à la section 5, puis dessinez le diagramme.

Apportez le diagramme à la séance 2, avec la collecte du chapitre 1.01 : le chapitre 1.06 commence par la comparaison.

Le cahier des charges se remet avec le portfolio, avec la colonne « réel » remplie et l'écart le plus grand expliqué. Quand un besoin est terminé, notez son temps réel le jour même.

À retenir#

• Un besoin s'écrit avec un critère d'acceptation qui se vérifie en ouvrant le site ou en lançant un test.
• Le cahier des charges suit les pages du site, de l'accueil au back-office, et garde le minimum noté pré-rempli.
• Vos bonus sont libres, mais chacun porte un critère et une estimation, sans jamais remplacer un point du minimum.
• L'estimation se compare à ce que vous avez fait en 5XCOS, et l'écart avec le réel s'explique à la remise.
• Le diagramme de classes se dessine à partir de vos besoins et de la fiche projet, et il devient vos migrations à la séance 2.