ÉTUDE D’ARCHITECTURE · Spécification
Ce qu’une bonne spécification tranche
Rien ici n’est propre à une plateforme. Tous les projets écrivent des spécifications, et celles qui tiennent tranchent en général les mêmes quelques points.
Pourquoi c’est important
Une spécification justifie sa place en tranchant des décisions. Celles qui tiennent pendant la réalisation sont celles qui ont répondu aux questions que personne n’avait encore pensé à poser — ce qui se passe quand un service est indisponible, qui décide quand le document est ambigu, où le travail s’arrête. Ces décisions sont prises de toute façon. La seule question est de savoir si elles le sont tôt, par les personnes à qui elles reviennent, ou tard, par qui se trouve disponible.
La décision — Traiter la spécification comme l’endroit où l’on tranche les décisions, pas comme l’endroit où l’on décrit la fonctionnalité. Moins de mots sur le cas nominal, plus sur les bords.
Ce que cela apporte — Le métier tranche ce que le métier doit trancher, au moment où trancher coûte peu. Les reprises diminuent, parce que moins de choix sont faits par la mauvaise personne sous pression.
Le risque évité — Un développeur qui décide, un vendredi à dix-sept heures, ce que voit un client quand un paiement échoue.
En une phrase : une bonne spécification n’est pas plus longue qu’une mauvaise. Elle dépense ses mots autrement.
Le problème
Demandez d’où viennent les reprises et la plupart des gens répondront : du code. C’est rarement le cas. Elles viennent en général d’une décision qui n’a jamais été tranchée, découverte au moment où on ne peut plus l’éviter.
Voici la forme que cela prend. Une spécification décrit une nouvelle fonctionnalité. Elle explique ce que voit le client, quels boutons existent, et ce qui se passe quand on les active. Elle est détaillée, relue, validée. Puis la réalisation commence, et en une semaine quelqu’un demande : que doit-il se passer si le prestataire de paiement ne répond pas ?
Personne ne sait. Le document ne le dit pas. Une réponse est donc fabriquée — vite, par une seule personne, sans celles à qui la décision revenait. C’est souvent une réponse raisonnable. Ce n’est simplement la décision de personne.
Non par négligence. La spécification a été lue par des personnes qui ont chacune supposé que la question avait été tranchée ailleurs — plus haut dans le document, lors d’une conversation précédente, par quelqu’un de plus proche du sujet. C’est cette supposition qui rend l’échec silencieux. Personne ne remarque la question qui n’a jamais été posée.
C’est le schéma, et il se répète. Chaque question non tranchée devient une petite décision sans propriétaire. Ensemble, elles deviennent la reprise.
À quoi sert une spécification
Le recadrage utile est celui-ci : le rôle d’une spécification n’est pas de décrire la fonctionnalité. C’est de trancher les décisions que la réalisation devrait sinon deviner.
Ce sont deux travaux différents, et ils tirent dans des directions différentes. Décrire une fonctionnalité, c’est écrire sur ce que tout le monde se représente déjà. Trancher des décisions, c’est écrire sur ce à quoi personne n’a encore pensé — ce qui est plus difficile, moins gratifiant, et beaucoup plus utile.
La plupart des spécifications font bien le premier travail. Le second demande un effort délibéré, parce que rien dans le fait de décrire une fonctionnalité n’y conduit.
Où partent les mots
Mesurez la longueur d’une spécification courante : environ quatre-vingts pour cent décrivent le cas nominal, celui où le client fait ce qu’on attend, où chaque système répond, où tout le monde est content.
C’est la partie sur laquelle tout le monde est déjà d’accord. Elle ne provoque presque aucune reprise, parce qu’il n’y a jamais eu de désaccord.
Les vingt pour cent restants — ce qui se passe quand ça se passe mal, qui décide, où cela s’arrête — sont à l’origine de presque toutes les reprises. Ils reçoivent le moins d’attention parce qu’ils sont les plus difficiles à écrire, et ceux dont les réponses ne sont encore évidentes pour personne.
Le remède n’est donc pas un document plus long. C’est le même document, dépensé autrement.
Les décisions qui méritent d’être tranchées
Voici celles qui paient le plus tôt on les tranche. Aucune n’est technique. Chacune revient au métier — et chacune, laissée ouverte, atteint la réalisation plus tard sous forme de surprise technique.
Ce que voit le client quand quelque chose est cassé. Tranchez-le et le métier possède les mots qu’un client rencontre au pire moment. Un prestataire de paiement ne répond plus. Un service de fidélité est indisponible. Un transporteur ne peut pas donner de date. Que doit voir le client ? C’est une question de confiance, et de savoir si l’on préfère perdre la vente ou risquer la commande — ce qui en fait une décision métier, pas technique. Laissée ouverte, elle est posée pour la première fois pendant un défaut en production, et tranchée par qui débloque le ticket.
Les mots eux-mêmes. Tranchez le texte du message et le client lit quelque chose qui a été choisi. Laissé ouvert, quelqu’un l’invente tard, et les mots inventés sont ceux qui atteignent de vraies personnes. « Une erreur est survenue » est une phrase qu’aucun métier n’a jamais choisie, et elle est sur plus de sites qu’on ne le voudrait.
Combien, et que se passe-t-il le jour du lancement. Un chiffre ici permet de dimensionner la conception avant de la construire. Une fonctionnalité utilisée deux cents fois par jour et une fonctionnalité utilisée deux cent mille fois par jour ne sont pas la même fonctionnalité, même quand les écrans sont identiques. Sans le chiffre, le dimensionnement se fait après coup — c’est la manière habituelle dont un lancement devient un incident.
Quels marchés, quelles marques. Tranchée en semaine un, une différence entre marchés est un paragraphe. La même différence trouvée en semaine six est une reconception, parce que la forme de la solution est déjà fixée. C’est l’une des questions les moins chères à poser tôt et les plus chères à répondre tard.
Où cela s’arrête. Une ligne disant ce qui est hors périmètre est ce qui permet à quelqu’un de dire non plus tard. La dérive du périmètre est rarement un combat ; c’est une série de petits ajouts raisonnables, qu’aucun ne peut refuser, faute de ligne à montrer. La phrase « cette version n’inclut pas X » vaut plus que trois pages décrivant X.
Qui décide quand le document est ambigu. C’est la phrase la plus utile qu’une spécification puisse porter. L’ambiguïté n’est pas le problème — tout document en comporte. L’ambiguïté sans nom en face est le problème, parce qu’elle est levée en silence par la première personne qui l’atteint.
Si l’on peut désactiver. Tranché avant la réalisation, c’est une contrainte de conception qui ne coûte presque rien. Laissé jusqu’à un incident, c’est une crise avec un public. Peut-on éteindre cela si ça tourne mal, et qui a l’autorité de le décider ?
Comment on saura que cela fonctionne. Des critères que quelqu’un peut vérifier, et sur lesquels deux personnes peuvent être en désaccord, transforment « terminé » en quelque chose d’observable. « La fonctionnalité marche » n’est pas testable. Une liste de critères d’acceptation qui reformule l’exigence avec d’autres mots non plus — un échec très fréquent et facile à manquer, parce que la liste paraît complète.
Comment on saura que cela valait la peine. Un chiffre, un comportement, ou une réclamation qui cesse d’arriver. Tranché, cela vous dit s’il faut en faire davantage. Laissé ouvert, chaque fonctionnalité est un succès, ce qui vide le mot de son sens.
Quelles données sont collectées, et sur quelle base. Savoir si le métier demande un consentement, et pour quoi, est une décision métier avec une portée juridique. Tranchée tôt, c’est une donnée de conception. Laissée ouverte, elle arrive comme une surprise technique, en général tard, en général quand il s’avère qu’il faut une bannière de consentement.
Ce qui est attendu en matière d’accessibilité. Décidé ici, ou pas du tout. C’est bien moins cher en ligne dans une spécification qu’en programme de correction, et sur certains marchés c’est une obligation légale, pas une préférence.
La limite la plus importante
Rien de tout cela ne plaide pour écrire davantage.
Une spécification ne peut pas tout répondre d’avance, et prétendre le contraire produit du remplissage. Certaines choses ne sont réellement pas connaissables au moment où le document est écrit. Forcer une réponse produit une phrase assurée qu’il faudra défaire ensuite, ce qui est pire qu’un manque assumé. La démarche honnête consiste à nommer l’inconnue, nommer qui la tranchera, et dire à peu près quand. « Nous ne savons pas encore, et l’équipe commerciale décidera avant le début de la réalisation » est une réponse complète et utile. « À confirmer » tout seul ne l’est pas.
Le sur-détail a son propre mode d’échec. Un document de quarante pages que personne ne lit ne protège personne. Il est validé sur confiance puis ignoré, ce qui est pire qu’un document court réellement utilisé, parce que tout le monde croit que les questions ont été traitées. Dimensionnez la spécification au changement : un petit ajustement et une nouvelle intégration de paiement ne méritent pas le même traitement.
Et ce n’est pas une demande de travail supplémentaire aux équipes produit. C’est une redistribution. Moins de mots sur les écrans que tout le monde comprend déjà. Plus sur les bords auxquels personne n’a pensé. Bien menée, le document raccourcit et les désaccords ont lieu plus tôt, là où ils coûtent peu.
Options envisagées
| Option | Décision | Raisonnement |
|---|---|---|
| Dépenser les mots sur les bords, et nommer un responsable pour chaque question ouverte | Retenue | Ne coûte rien en longueur. Déplace les conversations difficiles là où elles sont bon marché, et donne à chaque inconnue une personne plutôt qu’une étiquette. Accepte que certaines sections soient inconfortables à écrire. |
| Écrire des spécifications plus longues et plus détaillées | Rejetée | Traite le problème comme un manque d’effort. Produit des documents que personne ne finit, et les manques demeurent — ils sont seulement plus difficiles à trouver. |
| Laisser les manques et les régler pendant la réalisation | Rejetée | C’est l’état actuel dans la plupart des endroits, et cela mérite d’être nommé clairement. Les questions reçoivent bien une réponse. Elles la reçoivent tard, de qui est disponible, sans les personnes dont c’était la décision. |
| Un long modèle que chacun doit remplir avant de commencer | Rejetée | Charge tout le document au moment où l’on en sait le moins. Force des réponses inventées dans des sections qui auraient pu dire honnêtement « pas encore », et une réponse inventée est pire qu’un manque parce qu’elle a l’air réglée. |
| S’appuyer sur des ateliers et la discussion plutôt qu’un document | Rejetée | La discussion a une vraie valeur et doit continuer. Mais six semaines plus tard personne n’est d’accord sur ce qui a été décidé, et une décision non écrite n’est pas une décision : c’est une impression partagée. |
Les options rejetées échouent pour la même raison de fond. Chacune laisse sans réponse la question de qui décide, donc la décision se prend quand même, quelque part où personne ne regarde.
Ce que je surveillerais
- Des spécifications qui décrivent l’écran au lieu de la décision. Une description détaillée d’une page dit à quoi elle ressemble, pas ce qui doit se passer quand ce qu’il y a derrière tombe. C’est la seconde partie qui coûte de l’argent.
- Des « à confirmer » sans propriétaire. Une inconnue nommée est un plan. Une inconnue anonyme est un défaut à retardement. Chaque point ouvert a besoin d’une personne, pas d’une étiquette.
- Des critères d’acceptation qui reformulent l’exigence. Si le critère ressemble à l’exigence avec les mots dans un autre ordre, rien n’a été rendu vérifiable. Demandez si deux personnes pourraient regarder le résultat et être en désaccord.
- Une spécification validée mais pas lue. La validation n’est pas la compréhension, et les longs documents sont validés sur confiance. Si personne ne sait le résumer, la signature vaut peu.
- L’ambiguïté levée en silence. La chose la plus coûteuse de tout ce texte. Quand un développeur fait un choix de jugement parce que le document était muet, la décision ne laisse aucune trace et personne ne sait qu’elle a été prise. Surveillez les décisions qui n’apparaissent que dans le code.
Ce que cela apporte
- Les personnes qui doivent trancher tranchent, au moment où changer d’avis coûte peu.
- Les reprises diminuent, car moins de choix sont faits tard par des gens qui cherchaient seulement à se débloquer.
- Les mots qu’un client lit dans un mauvais moment ont été choisis par le métier, pas improvisés en fin de sprint.
- Le périmètre a une défense, parce qu’un écrit dit où il s’arrête.
- Les inconnues sont visibles et attribuées, au lieu d’être découvertes une par une pendant la réalisation.
Rien de tout cela ne demande un nouveau processus ni un nouvel outil. Cela demande le même document, avec son attention déplacée vers les parties difficiles à écrire.
À lire aussi : Utiliser l’IA comme moteur de cohérence pour le travail d’architecture tient le même raisonnement une étape plus loin dans le processus, pour la conception technique plutôt que pour la spécification fonctionnelle : fixer la structure, garder le jugement chez une personne.