Rédiger une spécification que les développeurs liront vraiment

Ce qui y entre et ce qui n'y entre pas

Une spécification qui décrit chaque pixel devient un document que plus personne ne met à jour au bout de deux semaines. Une spécification qui ne décrit qu'une vision génère vingt questions par jour. Le juste milieu : pour chaque fonctionnalité, qui l'utilise, ce qui se passe sur le chemin normal, ce qui se passe en cas d'échec, et la condition qui permet de dire qu'elle est terminée.

Les critères d'acceptation évitent la plupart des désaccords. « L'utilisateur reçoit une notification en moins d'une minute » est un critère ; « le traitement sera rapide » est un souhait.

Décrire des parcours, pas des écrans

Décrivez le parcours comme une séquence : état de départ, action, résultat. Écrivez ensuite les chemins d'échec — pas de connexion, l'utilisateur a fermé en cours de route, le fichier est corrompu, l'autorisation est refusée. Dans les projets réels, les chemins d'échec représentent la moitié du travail et un quart de la spécification.

Les écrans sont refaits ; les parcours restent. C'est pourquoi la maquette est liée depuis la spécification plutôt qu'intégrée dedans.

La partie que tout le monde saute

Écrivez explicitement ce qui est hors périmètre pour cette version. Une liste « pas maintenant » est un outil de pilotage, pas une excuse : elle permet de dire « exact, et cela vient ensuite » au lieu de rouvrir le débat à chaque réunion.

Ajoutez les hypothèses sur lesquelles vous vous appuyez. Une hypothèse écrite est un risque géré ; une hypothèse restée dans une tête est une surprise.