Au fil des ans, j’ai lu / écrit des centaines de spécifications d’éléments généraux . Certaines étaient brillantes
Voici ce que j’ai appris à Microsoft qui a changé la façon dont je pense aux spécifications. Une spécification n’est pas une bible; c’est un outil' . Comme n’importe quel outil, vous l’utilisez pour accomplir un travail.
Treat a spec as sacred, un document inchangable et vous ' construisez la chose erronée parfaitement M SK2 fonctionnent très, très rapidement dans la direction erronnée'). Traitez-le comme un outil vivant et vous
Cette approche agile à l’égard des spécifications crée un défi particulier: si la fonctionnalité peut évoluer au fur et à mesure que vous apprenez , comment tu l’estime-t-il ?
En général, un principe que j’ai respecté dans ma carrière.
Fondamentalement; une spécification de fonction est un outil de conversation pour améliorer la fonctionnalité NON un dogmatiqueM SK1 LA loi inchangée.
L’agilité n’est pas un obstacle à la mise en place d’un système de gestion des risques. Stratégie économique pour bâtir la bonne chose sous l'incertitude. Les spécimens vivent à l’intérieur de cette incertitude ,, donc ils doivent être aussi agiles Manifeste Agile, laissez-le devenir la façon dont vous pensez au développement de tout ce que vous faites . Pensez à cela comme à un modèle de conception pour le développement des produits . Il ne s’agit pas d’un processus, mais d’une mentalité.
Chaque boucle accroît la distance entre “ideaM SK1 et “utilisable”:
Mise à jour de la spécification après chaque boucle. Le journal des changements est le L'histoire de ce que vous avez appris.
Le principe le plus important pour écrire les spécifications: Commencez toujours par le problème, non la solution.
Ce modèle est simple:
I' j’ai vu des spécifications innumérables qui sautent directement dans "User clicks button X which calls API Y" without ever explaining what the user is actually trying to achieveM SK3 This is arseMNK4backwardsMRK5 Les détails de la mise en œuvre devraient s’écouler naturellement à partir d’une compréhension du problème MNK6
Rappelez-vous que les développeurs sont des machines de construction de fonctionnalités (code est l’outil pour livrer des fonctionnalités a besoin de faire PAS comment le faire. si vous avez une personne UX qui est responsable de la spécification UX, alors le développeur et eux devraient travailler ensemble. Le point est d'établir la meilleure fonctionnalité pour l'utilisateur qui peut changer et quiconque est habilité à faire pression pour le changement ( dans la spécification ) et à avoir ce processus d’examen tester l’idée
flowchart TD
A[Feature Idea] --> B[Spec / Proposal]
B --> C[Visuals: Flowcharts, Figma, UI Mockups]
C --> D[Implementation]
D --> E[Internal Testing]
E --> F[Feedback Loop]
F -->|Refine| B
F -->|Ship| G[Release to Users]
G --> H[User Feedback]
H -->|Iterate| B
Avant de rédiger un mot sur la mise en œuvre, vous devez répondre à une question. Pourquoi?
Pourquoi construisons-nous ce système?
Une bonne spécification commence avec:
C’est là que la plupart des spécifications vont tits-upM SK1 Trop vague et les développeurs sont laissés à penser; trop détaillés et vous 're micromanaging implementation choices that developers are better qualified to makeMSC4
Le truc consiste à spécifier LE QUESTION Il faut que cela se fasse sans prescrire COMMENT il se produit. Par exemple:
BonLorsqu’un utilisateur tente de soumettre un formulaire comportant des données invalides, il doit recevoir une rétroaction immédiate indiquant les champs à corriger.
Faible: "Aux fins de la présentation du formulaire, le bouton de soumissionM SK3s onClick l'interprète devrait appeler validateFormMSC4 qui se répète par le biais du formulaireArraye des champs vérifiant chaque champMNK5valeur contre sa validationMRK6propriété regex et si aucun défaut doit appeler showErrorMEK7 avec le champ MNK8nom et validation.paramètres de messageMNK10
La première m’indique quelle devrait être l’expérience de l’utilisateur; Je peux la mettre en œuvre dans React, VueM SK2 JavaScript vanilla , ou pigeon transporteur pour tout ce qui importeMSC4 La seconde suppose des détails de mise en oeuvre qui pourraient être complètement erronés pour le cahier technique ou introduire des contraintes inutilesMST5 Différentes personnes ont des forces différentes souvent la personne qui écrivait la spécification n’est pas MST6t technique Mst7 n’était pasM st8t celle qui écrirea le codeMSt9 Imaginez vous être un chauffeur de taxi et ne pas avoir été informé du lieu de destination mais chaque changement de vitesseM ST10 miroir etc.
## Utiliser des images / diagrammes de débit; Obtenir le point à travers
Rappelez-vous que vous 'essayons de faire comprendre aux gens ce que vous suggérez 're suggérant Veiller à ce que vous soyez compris. Utilisez les outils dont vous avez besoin
Dans un Wiki mermaid.js, les diagrammes sont GREAT pour ce ! ; rappelez que l’AI est très efficace pour les produire aussi en donnant une description textuelle
Certaines personnes peuvent analyser des descriptions écrites, certaines ont besoin de photos et de filmsM SK1
flowchart LR
A[User on Profile Page] --> B[Click 'Add Profile Picture']
B --> C[Upload Dialog Opens]
C --> D[Select Image File]
D --> E[Preview + Crop Options]
E --> F{User Confirms?}
F -->|Yes| G[Profile Updated with New Picture]
F -->|No| C
G --> H[User Sees Updated Profile]
S’il y a une chose, je l’ai apprise. Les utilisateurs trouveront des façons de briser votre merde que vous n'avez jamais imaginé.
Une bonne spécification ne décrit pas simplement le chemin heureux, mais considère qu’il s’agit d’un chemin positif.
Il n’est pas nécessaire de résoudre toutes ces questions dans la spécification, mais il faut reconnaître qu’elles existent.
Pour MANY, il est probable que ces spécifications ne soient pas applicables à ce spec.
Ces exigences ne devraient pas être prises en considération lors de l’examen du code.
De même, s’il y a des contraintes de performance qui sont importantes M SK1 Cette recherche doit être effectuée sous 200ms pour les ensembles de données d’un nombre maximal de millions d’enregistrements
Voici le modèle que j’utilise pour les spécifications de fonctionnalités.
Un paragraphe ou deux résumant ce que nous construisons et pourquoi cela est important.
Quel est l’état actuel de la situation?What' What prompted this feature?What have users been asking for?What would help us make more money?
Je l’ai reçu—let Les histoires des utilisateurs avec des personnes enduites dans, de sorte qu’il’ n’est pas seulement une liste de contrôle mais une carte vivante de la façon dont les différents types d’utilisateurs interagissent avec le système .
Les histoires des utilisateurs ne sont pas seulement une boîte, mais aussi un exercice d’affichage. Intégrer des gens réels et leurs objectifs. Vous connaissez, vos utilisateurs c'est tout le point de construire cette merde.. En assurant l’ancrage de chaque histoire à une personne, vous vous forcez à réfléchir aux habitudes d’utilisation réelles.
En fin de compte, les personnes sont un bon moyen d’identifier comment votre logiciel peut servir différents TYPES d’utilisateurs. Peut-être Alex a besoin d’un tableau de bord pour voir les problèmes de sécurité dans votre fonctionnalité, peut-être Morgan a besoin de ses permissions restreintes pour lui empêcher de détruire des choses, etc.
En tant que [Personne / type d'utilisateur] Je veux [pour faire quelque chose] Ainsi que [J’ai atteint un objectif.
L'article 5 de la Loi sur l'immigration et le statut des réfugiés “soit queM SK1 La clause est la garantie contre les caractéristiques de construction dont personne n’a besoin.
| Personne | Historique | Pourquoi cela est important |
|---|---|---|
| Alex (Administrateur) | En tant que Administrateur, Je veux attribuer des rôles et des permissions de façon à ce Je peux assurer la sécurité des données et leur conformité. M SK1 Prévient l'accès non autorisé et maintient le système digne de confiance | |
| Jamie Utilisateur occasionnel, Je veux un tableau de bord simple de façon à ce Je peux voir rapidement l’information la plus importante sans être surpeuplée. M SK1 Réduit les frictions et augmente l’adoption | ||
| Priya Utilisateur de puissance, Je veux créer des flux de travail personnalisés de façon à ce Je peux automatiser les tâches répétitives et économiser du temps. | Débloque l'efficacité et les cas d'utilisation avancées. | |
| Morgan (Nouveau(e) arrivant(e). Nouveau-commissaire, Je veux des guides et des conseils d'outils de façon à ce Je peux apprendre le système sans se sentir perdu. M SK1 Améliore l’aéronef et la retenue. | ||
| Taylor (Contrôleur de l’entreprise Les intervenants, Je veux recevoir des rapports réguliers par courriel de façon à ce I can track progress without logging in. M SK1 Keeps decision -makers informed and engaged. |
Il s’agit de votre viande et de vos pommes de terre.
Pour chaque exigence, spécifier,
Objectifs de rendement,exigences en matière de sécuritéM SK1standards d'accessibilité ,browser/support des périphériquesMSC4 Ne pas assumer que ces éléments sont évidentsMNK6 Mais dans certaines équipes, ils peuvent être TOTALES AUTRES ÉQUIpesMMK7mais ne pasMRK8ne pas perdre l'attentionMBK9 Si une partie de votre cycle devient un cascade alors vousMEK10 avez perdu l'agilité par définitionMDK11
Cette section est tout aussi importante que ce que vous faites.
Pourquoi cela importe:
Exemples de biens hors champ d’application:
Si quelqu’un fait valoir qu’une question hors de la portée de l’article - du - devrait figurer dans le champ d’application de celui-ci, , indique que ' est une conversation qui vaut la peine d’être tenue AVANT le début du développement , n’est pas à mi-chemin de mise en œuvre
Soyez honnête quant à ce que vous ne savez pas.
Quels autres systèmes/teams /features dépendent-ils de ce qui se passe?
Comment l'AQ vérifiera-t-elle cette question?? Ces déclarations devraient être concrètes.
C’est là quelque chose dont on ne parle pas assez. Les spécifications peuvent comporter des erreurs too.
Une erreur de spécification se produit lorsque la spécifications elles-mêmes sont incorrectes.
Lorsque vous trouvez une erreur de spécification en tant que développeur, vous avez quelques options:
C’est presque toujours la bonne réponse.
Envoyez un message clair à quiconque possède le spec:
Veuillez le faire par écrit.
Parfois, vous serez tenté de construire simplement ce qui est spécifié, même si vous le savez. DON'T DOT THIS.
J’ai vu les développeurs mettre en œuvre des spécifications qu’ils savaient être erronées parce que "c’est ce que 'tout cela dit de faire" et ensuite agir surprenant lorsque la QA le rejette ou que les utilisateurs se plaignent.
L’exception est que si vous' avez soulevé la question(s), ,, on vous a dit d’aller de l’avant, , et que vous l’avez reçue par écrit(s).
Si vous êtes certain que vous savez ce qu’il faut dire dans la spécification, vous serez peut-être tenté de le corriger par vous-même.
Ne changez jamais silencieusement les exigences. C’est ainsi que vous obtiendrez des caractéristiques de construction dont personne n’a demandé
La meilleure approche consiste à prévenir les bugs spéciaux en premier lieu:
Certaines personnes pensent que plus de détails sont toujours meilleurs.
Si votre spec se transforme en guerre et paix, vous êtes soit :
Le problème opposé : "Construire un système de rapports ." Oui M SK3 Je vous félicite pour cela MSC4 IM SK5 Je mettrai tout simplement quelque chose sur la table et nous' Nous verrons s’il correspond à ce que vous avez eu dans votre tête.
Si votre spécification peut être pleinement saisie dans une seule phrase, il 'il n’est pas un spécificateur;ilM SK3il s’agit d’un souhait vague
"Nous avons besoin d’un clavier de bordM SK1est-ce'il n’est pas une exigence ;c’est une solution préconçue
Les exigences qui changent quotidiennement sont les suivantes :
" Alors que nous sommes là, ' Nous pourrions-nous y être aussi?
C’est le changement de mentalité qui a changé la façon dont je écrive les spécifications: Traitez votre spécification exactement comme vous traitez le code source.
Vos spécifications devraient être contrôlées en version à côté de votre code. Vérifiez-les dans les fichiers. Suivez les changements de traçageM SK2 Rédigez des messages d'engagement significatifs lorsque vous les mettez à jour . Ceci crée une histoire de la façon dont les exigences ont évolué
À Microsoft, nous avons maintenu les spécifications dans les mêmes répertoires que le code.
Tout comme le code doit être réfactorié,, aussi les spécifications. À mesure que vous apprenez davantage pendant la mise en oeuvreM SK2, la spécification devrait évoluer pour refléter cet apprentissage .
Trouver une meilleure façon de résoudre le problème? mettre à jour la spécification pour refléter la nouvelle approche et expliquer pourquoi vous avez changé de direction . découvrir un cas en bordure que vous n’avez pas examiné ' ne l'avez pas pris en considération
Les spécifications après le développement devraient être plus raffinées que celles avant le développement.
Une spécification n’est pas 't "accompliquéeM SK2 lorsque le développement commence, c’est 'c’est juste ♫'réaliste~' pour ce stade . Celle-ci ' est faite lorsque la fonctionnalité se déplace et devient un mode d’entretien
Cela ne signifie pas que la spécification devrait changer quotidiennement.
Pensez-en de cette façon: si vous voudriez' ne laisser pas les commentaires périmés dans le code , ne laissez pas l’information périmée dans les spécifications
Il y a ici quelque chose qui ne fait pas l’objet d’un débat suffisant. votre spec devient la base de tout ce qui vient après.
Plans d'essai: L'AQ écrit les cas d'essai en fonction de la spécification. Si le spécificateur est désuet , Les essais font l'objet d'une vérification erronéeM SK3 Vous obtiendrez des positifs faux
Documentation: Documentation de l'utilisateurM SK1 Dossiers API, Systèmes d'aide , votre fantaisie agent de soutien RAG AI | - ils allèguent tous à la spécification\ . Si le spécificateur décrit des éléments qui ne sont pas existants ou manquent les éléments qui le sont |, vos dossiers sont erronés depuis le premier jour
Développement futur: Quand quelqu’un a besoin d’étendre la fonctionnalité six mois plus tard , ilsM SK2 liront le spécimen pour comprendre comment elle fonctionne . Si elle ne correspond pas à la réalité MSC4 elles,ilsMST6commenter avec des hypothèses incorrectes MST7
Débarquement: Les nouveaux membres de l’équipe apprennent le système partiellement en lisant les spécifications . Les spécificateurs périmés leur inculquent un modèle mental erroné sur la façon dont fonctionnent les caractéristiques
C’est pourquoi la spécification doit demeurer courante. Il ne s’agit pas seulement de la mise en oeuvre initiale ; il est fondamental pour tout le reste
À Microsoft, nous avons traité les mises à jour des spécifications avec la même importance que l’actualisation du code. Les modifications de spécification ont fait l’objet d’une révision . Elles ont été mises en version parallèlement au code
Si vous modifiez le code mais ne mettez pas à jour la spécification, vous aurez créé un DEBT TECHNIQUE.
# La relation entre spec et mise en œuvre
Voici ce que les jeunes développeurs ne comprennent souvent pas : La spécification n'est pas la source de la vérité; le code est.
Les spécifications vous disent ce que vous cherchez à bâtir.
Cela signifie:
Différents gens ont besoin de choses différentes des spécifications:
Exécutifs - Vous voulez connaître la valeur de l’entreprise et le calendrier approximatif . Donnez-leur un aperçu et des critères de réussite M SK2
Gestionnaire de produits - Besoin de comprendre comment il s’inscrit dans la stratégie et la feuille de route des produits plus vastesM SK1 Donnez-les les histoires d’utilisateurs et les dépendances
Développeurs - Besoin de suffisamment de détails pour mettre en œuvre correctement sans être informé de la façon dont ils doivent faire leur travail . Donnez-leur les prescriptions
QA - Besoin de savoir comment vérifier qu’il fonctionneM SK1 Donnez-les les critères d’acceptation.
Des concepteurs - Besoin de savoir quelle devrait être l'expérience de l'utilisateur . Donnez-leur les histoires d'utilisateur et les flux d'interaction M SK2 Il est encore préférable qu'ils développent un spec UX / tableaux d'histoire en parallèle tout en travaillant avec le dev
Une bonne spécification sert tous ces auditoires sans être bloquée. Utiliser des sections et une structure pour que les gens puissent lire ce qui leur importe
Avant d’appeler une spécification faite, demandez à vous-mêmes:
Mais nous sommes agiles. Nous n’avons pas besoin de spécifications.
L’agilité n’implique pas 't, c’est-à-dire "pas de planification" ou "absence de documentationM SK4 Il s’agit de réagir au changement par suite d’un plan. Les spécifications sont des outils, non des contrats. Vous les créez avec suffisamment de détails pour commencer.
La différence fondamentale est le format ou la longueur de ;, mais aussi sa mentalité et son processus.
Espèces des chutes d'eau:
Specs agile:
L’approche de la cascade suppose que vous pouvez spécifier tout parfaitement avant d’écrire une ligne de code. Que ' est une belle fantaisieM SK2 Dans la réalité, vous découvrirez la moitié des exigences une fois que les utilisateurs ont effectivement essayé la fonctionnalitéMSC4 Planifier pour celaMST5 l’adopterM ST6 Les utilisateurs sont les testers ULTIMATEM st7 Ils peuvent détruire ce qu’ils n’ont pas faitMst8 ils ne savent même pas qui vous êtesMSt9 il a été fait à un rythme qui semble violer la causalitéM St10 attendez-le,MST11 le planifiez,Mst12 le registrez et le corrigez,MSt13 et le ajoutez à une spectre future MS ST14 cette si vousM S ST15 vous êtes encore dans la spectre,MS S ST16 s M S ST17 durée de vie,M S S ST18
## Les boucles de rétroaction sont tout
Dans le cadre d’un spectage agile, les boucles de rétroaction sont votre meilleur ami.
Rétroaction du développeur: "L'approche initiale a gagné't ne fonctionne pas parce que XMSC3 IM SK4m propose Y au lieu de l'amendement+." \→ Mise à jour des spécifications pour refléter la nouvelle approche et pourquoi elle a changé+. En fin de compte, vous='vous êtes ALWAYS le premier 'utilisateur~' d'une fonctionnalité~. Si cela semble une merde~M SK12sepc bug and get it sorted (Even if you stop whatever sprint ♪/ spike etc to do it ♪
Rétroaction des utilisateurs: Essayez la fonction avec des utilisateurs réels ( même à l'interne). "Ce n'apporte pas de solution à mon problème car Pivot la spécification selon ce que vous apprenez.
Rétroaction sur la mise en œuvre: À mesure que vous construisez,, vous détectez les cas à bordM SK2 les contraintes techniques , ou des approches plus efficaces
Rétroaction en matière de QA: "La spécification dit X, mais n’a pas pris en considération le scénario YM SK2
Chaque cycle de rétroaction permet d’améliorer la spécification.
C'est la raison pour laquelle les spécifications des chutes font souvent défaut: elles échappent aux cycles de rétroactionM SK1 Au moment où vous découvrez que le spec était erroné , vous' avez construit la chose erronée et MSC4 changer la spécification
Une grande chose, rétroaction aussi tôt que possible. C'est pourquoi j'ai construit LLMApi il vous aide à construire un BIT puis à utiliser des données fausses pour obtenir une rétroaction utile.
Voici ce qui fait nerveux les gestionnaires de projet traditionnels. il' est tout à fait bon si la spécification initiale comporte des lacunes
Marquez les sections comme suit : "TBDM SK1 si vous ne le savez pas'ne sait pas encoreMSC3 Listez les questions ouvertes de façon éloignée . Soyez explicite sur ce que vous n’avez pas encore comprisMSSK5ne l’avez toujours pas compris
Ce n’est pas de la piètreté, mais de l’honnêteté. Vous ne connaissez rien, ', vous ne savez pas tout à l’avance.
Commencez par:
Ensuite, remplissez les lacunes au fur et à mesure que vous apprenez.
Acceptez-le maintenant: votre spécification changera au cours du développement. Si ce n’est pas le cas, soit vous avez eu une chance incroyable ou vous n’avez rien appris.
Changements à attendre:
Chaque changement devrait être:
L'historique de la version du spec' devient un document de ce que vous avez appris.
L’approche agile peut échouer si vous oublierez une chose cruciale: " changera " ne signifie pas
mauvaise spécification agile:
Bonne spécification agile:
Le spec est un document vivant, mais il n’est pas chaos. Il évolue sur la base de l’apprentissage et non des caprices.
Il ne fait jamais ce que vous voulez et il l’appelle toujours.
Il s’agit d’un processus dynamique dont le but principal est de bâtir les meilleurs produits aussi rapidement que possible. Manifeste Agile dit comme il l’a fait : « Le premier principe de ' est le suivant:
" Notre priorité la plus élevée est de satisfaire le client par le biais d'une livraison rapide et continue de logiciels précieux."
Il n’est pas important de s’enfuir en tirant du code parce que vous aimez le sentiment.
Il s’agit de savoir ce que nous devons savoir pour commencer à construire avec confiance.
Pour certaines fonctionnalités qui pourraient être:
Pour d’autres, il pourrait être ::
Ajouter des détails lorsque l’incertitude existe. Si tout le monde est d’accord sur la façon dont une chose devrait fonctionner, vous n’avez pas besoin de l’écrire en détail.
Mais au bout du compte, il y a suffisamment de détails pour lancer le cycle de rétroaction.
## Templates and AI: Getting Started Quickly
Ne pas trop considérer la spécification initiale.
Utiliser des modèles: Mettre en place un modèle de base avec les sections clés (Problème, RésolutionM SK3 Dans l'étendue du champ d'applicationMSC4 À l'extérieur de l'éventail de la zone d'utilisationMska5 Critères remplisM Ska6 Remplissez ce que vous savezMka7 Laisser les section(s) vides si vous ne le savez pasM ska8ne sait pas encoreMSKA9 Nommer celles-ci comme :
Un modèle simple pourrait être ::
# [Feature Name]
## Problem
[What's broken? What pain exists?]
## Proposed Solution
[High-level approach]
## What "Done" Looks Like
- [ ] Specific, testable criterion 1
- [ ] Specific, testable criterion 2
- [ ] Specific, testable criterion 3
## In Scope
-
-
## Out of Scope
-
-
## Open Questions
-
-
C’est ce qu’il faut faire. Il y a cinq minutes pour le remplir et vous avez assez pour commencer à discuter ou même construire.
Utilisation de l'AI pour dessiner des spécifications: Des outils comme Claude ou ChatGPT peuvent être brillants pour obtenir un premier ébauche. Envoyez-le le problème et quelques contextes
Mais - et cela est critique - don't let the AI 's thoroughness seduce you into adding everythingM SK2
L’AI aime être globale. ElleM SK1 vous donnera des sections sur les considérations de sécurité, Exigences en matière de rendementMSC3 Accèsibilité , InternationalisationMST5 Traitement d’erreurs MST6 EnregistrementM ST7 SurveillanceM st8 Stratégie de déploiementMst9 Plans de roulementMSt10 et dix-sept autres choses dont vous aurez peut-être besoinMSS11 finalementMSSS12
Débarrasser la majeure partie de cela. Gardez ce dont vous avez besoin NOW. Le reste peut être ajouté plus tard lorsque vous le aurez réellement besoinM SK2
Pensez au spec généré par l’AI- comme à un menu . Choisissez les bits qui sont importants pour le démarrage
L’objectif n’est pas ', il s’agit d’un spectre complet, mais de ;, et ' est suffisamment précis pour commencer à travailler. . Que ce soit une estimation rapide, ,, une décision sur la priorité ou simplement une clarté quant à ce que vous construisez pour vous-même.
Voici les changements apportés à l’agile Vous ne faites pas de spécifications et jetez-les sur le mur aux développeurs. Le spec est un effort de collaboration.
La meilleure approche que j’ai vu I'
Tout le monde contribue à la spécification.0 Aucun n’en possède exclusivement.1 Cette approche coopérative attire les problèmes tôt lorsqu’ils sont résolus.2 Il est plus économique de les régler que tard quand ils sont coûteux.4
Plus important encore, , signifie que la spécification reflète ce qui est réellement possible, mais non ce que quelqu’un souhaitait en isolement.
Voici' où les spécifications agiles diffèrent de celles traditionnelles: la fonctionnalité peut évoluer au fur et à mesure que vous la construisez.
Vous découvrez que votre approche initiale a été retenue' ne fonctionne pas ? Mise à jour de la spécification pour refléter la nouvelle approche.
Vous essayez la fonction et constatez qu’elle ne résout pas le problème.
La rétroaction de l’utilisateur révèle une meilleure solution? L’intégrer et expliquer le changementM SK1
Cette évolution est une caractéristique.
Mais cela crée un problème: si la fonction peut changerM SK1 comment l’estimer? Comment savoir quand vous le faites?
C’est le secret de l’agile: L’estimation est vraiment difficile lorsque les caractéristiques peuvent évoluer.
Les estimations traditionnelles supposent que vous saviez ce que vous construisez.
L’estimation agile reconnaît que vous ne connaissez rien'pas tout à l’avanceM SK1 La fonctionnalité pourrait changer au fur et à mesure que vous apprenez . Comment est-ce que vous estimez?
Vous estimez les plages, non des valeurs absoluesM SK1 Au lieu de ", cela prendra 3 semaines M SK2 vous dites "dans un endroit entre MSC4 et MSC5 semaines selon ce que nous découvrerons
Vous estimez en iterations. Nous passerons un sprint à l’exploration de cette question et ferons rapport sur ce que nous avons appris. Ensuite, nous pourrons estimer le reste avec plus de précision.
Vous utilisez le temps-box au lieu du champ d’applicationM SK1boxing. Nous passerons 2 semaines à ce projet. À la fin de 2 semaines, nous aurons la meilleure version que nous pourrons construire en cette périodeM SK6
Mais toutes ces approches ont une exigence essentielle : Vous devez savoir ce que "doit" signifie Sans une définition claire de fait,, une fonction peut continuer à métasser pour toujours.
Il s’agit d’une critique courante de l’Agile par rapport aux approches Waterfall.
C’est là que de nombreuses spécifications agiles se détruisent.
Sans une définition claire de ce qui a été fait, les caractéristiques ne se terminent pas, ' ne s’achèvent pas et ; mettent en métastase, . ne se propagent pas,. ne font que pousser des tendrils vers d’autres parties du système.
I' j’ai vu des spécifications comportant des critères d’acceptation comme
Ce n’est pas une définition de « fait », mais des aspirations vagues.
Le développeur doit savoir: quelle chose spécifique, lorsque mise en œuvre, signifie que je peux cesser de travailler sur cette fonctionnalitéM SK2
Bonne "doneM SK1 Les critères sont :
Faible: "Les commentaires devraient être modérésM SK2 Bon: "Les utilisateurs de l'administrateur peuvent approuver les commentaires, rejeter ceux-ciM SK3 ou supprimer les commentaires du panel d'administrateursMSC4 NonMNK5 Les commentaires approuvés ne sont pas visibles aux utilisateurs réguliersMRK6 Une notification par courriel est envoyée à l'Administrateur lorsqu'un nouveau commentaire est affichéMMK7
Faible: "La recherche devrait être rapideM SK2 BonLes résultats sont classés en fonction de la pertinence (full-text search score ) with date as tieM SK9breakerMSC10
Faible: "Le tableau de bord montre des mesures utilesM SK2 Bon: "Displays de tableaux de travailM SK2 vues totales de la page ( dernière 30 jours ), visiteurs uniques SMK6 dernière 30 journées), haut de la liste MESK9 articles par points de vue S( dernière 7 jours~), et répartition des visiteurs selon le pays~. Tous les paramètres sont mis à jour une fois l'heureMSC14
Remarquez la différence? Les bons exemples vous disent exactement ce qui doit exister et quand vous pouvez cesser d’ajouter des choses.
Rappelez-vous que j’ai dit plus tôt que la section Out of Scope est aussi importante que ce qui suit :
Pour chaque fonction, il y a des dizaines de choses que vous pouvez ajouter.
Dans le champ d'application: Commentaires nichés (un niveau de réponsesM SK2 À l'extérieur de la portée: Traitement des commentaires illimitéM SK1 Vote du commentaire , Traitement des commentaires, Sortage des commentaires le mieux possibleMSC4 permalinks de commentaires MSC5ils peuvent arriver ultérieurement en tant que fonctions distinctesMSM6
Maintenant, lorsque quelqu’un suggère que " devraitn 't les commentaires ont des votes supérieurs?" vous pouvez indiquer la spécification et dire MSC3que SMC4 est hors de portée pour cette iterationMSC5 Laissez l’examiner en tant qu’élément distinct une fois que les commentaires de base sont fonctionnelsM SK7
Oh et la prochaine spécification? Bon, vous avez déjà une foule d’idées bonnes non utilisées captées! Plus facile à commencerM SK2
Parfois, vous ne savez pas vraiment ce qui se passe.
À la fin de 2 semaines, nous ' évaluerons ce que nous avons appris et déciderons si nous voulons produire une seule approche, , essayer quelque chose de différent,, ou abandonner la fonctionnalité.
Mais remarquez que : vous avez encore un béton de construction " réalisée M SK2 condition МSK3 semaines , puis évaluer MSC5 VousM SK6 ne construisez pas seulement indéfiniment MST7 Ces explorations sont souvent effectuées dans un contexte tel qu’une Sprint dans SCRUM appelée une 'Spike'
Un Spike est l’un de ces ' aller jouer et trouver cette technologie ' il peut durer aussi longtemps qu’une imprimante
On s’attend à ce qu’une piste soit livrable au bout (qu’une chose autre que la personne qui y participe puisse tester pour le boucle ). Une Spike peut avoir, mais probablement le seul produit livré est les connaissances de l’équipe
Ils sont aussi intéressants pour les développeurs et ils aident l’équipe Je recueille souvent des idées de Spike pendant un projet et quand il y a une pause je laisse aux développeurs choisir d’en explorer une.
Même avec des critères clairs "donnée" Critères de l’utilisationM SK2 le champ d’application peut s’écrouler . Vous détectez les cas à bordMSC4 Vous vous rendz compte que les utilisateurs ont besoin d’une chose qu’ils n’avaient pas prise en considérationMNK5non examinéeMMK6 Comment traitez-vous de cette question sans rompre votre définition du fait?
Documentez-le, ne le faites pas Lorsque vous découvrez quelque chose de nouveau qui doit être ajouté, mettre à jour la spécification . Faire explicitement savoir que le champ d’application a changéM SK2 Obtenir l’accord des intervenants.
Cela sert à deux fins:
Si votre spec continue d’augmenter, , signifie que ' est un signal . soit vous construisez la chose erronée ( et vous devez revenir à l’avant et réexaminer ), ou cela devrait être de multiples fonctionnalités , ou vous devez réduire le champ d’application pour envoyer quelque chose utile plus tôt
À un moment donné, vous devez expédier. La fonctionnalité ne doit pas être parfaite ' il faut qu’elle soit utile
Un bon test: Les utilisateurs peuvent-ils tirer profit de cette fonctionnalité en sa forme actuelle?
Si oui, envoyez-leM SK1 Vous pouvez toujours iterer dans la prochaine version. Terminé ne signifie pas ' ne sera jamais amélioréMNK5 Cela signifie MMK6 résout le problème suffisamment bien que les utilisateurs profitent et nous pouvons passer à d'autres travauxMRK7
Si non, vousM SK1la tâche n’est pas encore terminée , indépendamment de ce que votre spécification dit.
La partie la plus difficile de l’agilité est ce qui suit :
Mais rappelez-vous que vous devez évaluer si vous la publiez à tous, avoir un groupe étroit pour A/B M SK2 UAT ( essais d’acceptation des utilisateursMSC4 QueMST5 est souvent une décision commerciale entourant le risqueMst6 Parfois, le public est EN VIGUEUR et voit une fonction de prévision partiellement complétée comme le GOSPEL POUR LA QUALITÉ DE votre SYSTÈMEM st7 Si c’est là un problème, un groupe contrôlé est plus sûrMSt9
# Le processus d’examen des spécifications
Une spécification n’est pas effectuée lorsque vous l’avez rédigé, mais lorsqu’elle a été examinée par les personnes qui la utiliseront.
Les meilleures pratiques que j’ai apprises à Microsoft: Les commentaires spéciaux fonctionnent exactement comme les commentaires de code. Ils sont 'coopératifs ,non antagonistesM SK2même si le club des garçons de Microsoft'' a souvent fait que les commentaires sur la spécification se sentaient comme un combat gladiatorial si quelqu’un était un pédophile.
Lors de l'examen des spécifications:
Lorsque votre spécification est examinée:
Les meilleurs examens des spécifications sont les conversations. Vous allez de l’avant à l’arrière. Vous apprenez les uns des autresM SK2 La spécification qui apparaît est meilleure que ce que l’une ou l’autre personne aurait pu rédiger seule .
Obtenir des commentaires de toutes les perspectives importantes:
Examen du développeur - Cela fonctionnera-t-il réellement?? Y a-t‐il des contraintes techniques que nous n’avons pas prises en considération?
Évaluation du produit - Cela résout-il le problème correct?? Il s’aligne-t-il sur la stratégie de produit? ? Qu’est-ce qui manque dans '?
Examen de la conception - Est-ce que l'expérience de l'utilisateur a un sens?
Examen de la QA Les critères d’acceptation sont-ils suffisamment clairs?
Vous n’avez pas besoin de signaux officiels.
De bons examinateurs posent des questions qui améliorent le spec:
Aucune de ces questions n’est achevée. Elles sont des questions authentiques qui permettent d’élaborer le spec.
Vous wont't accept every suggestion. That 's fineM SK3 But for each piece of feedbackMSC4
La spécification devrait s’améliorer avec chaque cycle d’examen. Si elle ne l’est pasM SK1t, vous 'vous n’écoutez pas ou vos réviseurs ne sont pas
Obtenez des commentaires de toutes ces perspectives avant d’entreprendre la mise en œuvre. Trouver les problèmes dans les minutes des coûts spéciauxM SK1 les trouver dans les coûts de production semaines.
Pour rendre tout cela moins abstracte, ici 's ce qu’une spécification pourrait ressembler pour la fonction de traduction automatique de marquage-à-tête que j’ai construite pour ce blog. Cela démontre les principes que nous avons discutésM SK3
Les articles de blog écrits en anglais excluent uniquement les autres -Les lecteurs anglophones parlant l’anglais .La traduction manuelle de chaque post dans plusieurs langues est un temps de publication considérable et retarde la parution. Nous avons besoin d’une solution automatisée qui traduit des articles de Blog markdown dans plusieurs langages cibles sans nécessiter une intervention manuelle pour chaque articleM SK4
Mettre en oeuvre un service de référence qui traduit automatiquement les fichiers de marquage vers des langues cibles configurées à l’aide du service de traduction automatique EasyNMT. Le service sera
Ces critères nous disent exactement quand nous pouvons cesser de travailler sur cette fonctionnalité:
Veuillez noter qu’ils sont spécifiques et testables. Nous pouvons vérifier chacune d’entre elles . Lorsque toutes les conditions sont remplies, nousM SK3on a terminéMSC4 Nous ne continuons pas à ajouter des fonctions comme MST6cotation de la qualité de la traduction MST7 ou SST8édition de traductions manuelles MSS9 à moins que nous n’élargissions explicitement le champ d’applicationMSS10
Plusieurs choses se sont produites au cours de l’élaboration qui ont raffiné le spec:
Ajustement de la taille des lots: Démarré avec 20- batches de lignes, mais a trouvé que les lignes 10 étaient plus fiables pour rester sous EasyNMTM SK4 sa limite verbale tout en gardant le contexteMSC5
Détection de l'image: Au départ, les noms de fichiers d'images figurant dans le marquage étaient envoyés au service de traductionM SK2 Partage des phrases en rupture. Détection additionnelle de l'extension des fichiers pour faire passer les cheminements d’images .
Disponibilité du service: EasyNMT peut être tempéré lors du démarrage . Ajout d’un contrôle de santé qui vérifie /model_name point final avant de tenter les traductions.
Entreposage Hash: Originalement prévu, stockage de bases de données pour les haches de fichiersM SK1 mais basé sur le système de fichier - .hash Les fichiers se sont avérés plus simples et ont évité la dépendance de base de données pour ce service.
Ces enseignements ont été regroupés dans la documentation et ont donné des renseignements similaires plus tard.
Cette spécification suit les principes discutés:
Le résultat: une fonctionnalité qui' est en cours de production depuis des mois , traduit automatiquement tous les articles sur le blog avec un minimum d’interventionsM SK3
Sur la base de ce que nous avons couvert, les questions qui se posent fréquemment sont les suivantes :
Il dépend de "small." Si c’est vraiment trivial 'changer le texte des boutonsM SK4 corriger une erreur de saisieMST5 nonM ST6 Mais si vous avez besoinM st7
Ensuite oui, même une spécification rapide aide. Il n’est pas nécessaire ' il n’y a pas besoin d’être formelM SK3 Quelques points de bullet dans un billet couvrant le problèmeMST4 SolutionM ST5 et les critères faits sont souvent suffisantsM st6
Le test: s’il est possible de vous expliquer dans deux phrases ce que " a fait M SK3 ressemble à quoi
Pointez sur la section hors champ d’application. Expliquez ce qui suit
S’ils insistent sur le fait que tout est tout aussi critique, ils suggèrent de choisir un autre travail à reporter plutôt.
Que' est une amende , pour autant queM SK2
Si la spécification n’est pas reconnaissable parce que vous avez complètement mal compris le problème à l’origine, que ' est un signe de faire plus d’exploration avant de commencer la prochaine foisM SK2 Mais on s’attend à une itération et à une apprentissage.
L’histoire de la version du spec' devrait vous raconter ce que vous avez appris.
Dans les Startups, cela est appelé 'Pivot' où vous commencez à bâtir un jeu et terminez par construire un système de messagerie incroyable au lieu d’un autre.
Don't get too locked in . If there's opportunities by pivoting TAKE THEMM SK3
Pour les bogues critiques: non, juste les corrigerM SK2
Pour les bogues complexes qui touchent plusieurs systèmes ou nécessitent des modifications architecturales: ouiM SK1 Traitez-le comme une fonctionnalité. Qu’est-ce queMSC3que vous avez défectué (qu’il y a problèmeMST5 comment vous le réparerez MST6comme vous le remédierons Mst7résolutionM st8de quelle façon vous le connaissezMSt9elle sera corrigéeMt10qui est réparéeMstr11critères remplisMtr12 ce que vous ne modifiez pasM str13Mr14 hors de portéeMrt15
Pour tout ce qui est entre-temps: utilisez votre jugement. Si la solution n’est pas évidenteM SK2 ou peut avoir des effets secondaires , une spécification rapide vous aide
Cela est particulièrement vrai pour les bugs de sécurité. Vous devez savoir exactement ce que vous corrigez et comment vous le vérifierez.
As formal as your team needs. Some teams are fine with detailed JIRA ticketsM SK1 Others want proper documents in version control.
La formalité est moins importante que le contenu
Vous pouvez l’écrire dans Markdown.
C'est la clé souvent invoquée pour le développement agile; et pourquoi je haine les cadres agiles (et SCRUM ). Le point central est que comme un spécificateur agile, votre processus doit être adapté aussiM SK3 Si écrire peu ne fonctionne pasMSC4pour une seule équipe mais beaucoup, mais cela se produitMST5fait ce qui suitM ST6Si aucun document ne fonctionne pour une petite équipe mais tous les documents fonctionnent pour une grande. Si les cycles de jour 5 fonctionnent pour une équipe mais que les sprints hebdomadaires 2 s’effectuent pour un autre team, le fait est le même. L’IDEA intégrale est de faire le meilleur produit; votre équipe est la machine FAIRE ce produit . Faire fonctionner la machine aussi doucement que possible
En tant que gestionnaire, regardez ce qui sont vos sorties; si le panneau a besoin d’un graphique brûlé puis comment pouvez-vous utiliser les données courantes pour construire un graphe?
En fin de compte, vous produisez des caractéristiques et ce dont les intervenants ont besoin. Si vous pouvez réduire l’impact sur l’équipe alors que ' est votre PARTIE
Vous avez encore besoin de spécifications.
En plus, vous devez encore:
Écrire des spécifications pour vous-même est comme écrire les tests d'unité: il se sent plus lentement maintenant mais économise du temps plus tard (comme moiM SK2 I'm dans mon MSC4sMNK5 Je FORGET SHIT ces jours-ci
Lorsque quelqu’un dit "OhM SK2 J’ai oublié de mentionner qu’il devrait aussi faire X," que ' n’est pas une clarificationMSC5 c’est ' son nouveau champ d’applicationMST7
Réponse: M SK1C'est là une bonne exigence ' mais ce n'est pas ce que nous avons convenu dans la spécification . Nous l'ajoutons à la section Out of Scope pour le moment et discutons de l'inclure ou de la sauvegarder pour la version
Si c'est vraiment une exigence (ne serait pas un bon
N’absorber jamais silencieusement la dérive de portée. Celle-ci ' détruira vos estimations et votre crédibilité.
Oui, si vous'vous faites des prototypes pour répondre aux questions ouvertesM SK2 NonMSC3si vous 'vous construisez une usine de production
Il est bon de prototyper pour apprendre.
Construire un code de production avant que la spécification ne soit prête signifie que vous 'es-vous apercevez les exigences . Vous ' construirez probablement la chose erronée
Exception: si vousM SK1 êtes propriétaire et développeur du produit (projet solo ), vous pouvez spécifier et coder simultanémentMSC4 Mais documentez toujours vos décisions au fur et à mesure que vous allez
Le ' jusqu’à ce que la spécification soit prête ' est une bonne façon de faire charger les dévs pour commencer M SK2 Évaluation des approches technologiques , écriture d’une plaque chaudière commune, etc.
Découvrez pourquoi:
Si les gens échappent aux examens des spécifications et construisent ensuite la chose erronée, ce n’est pas le cas. , Make the pain visible . " This wasn’'t in the spec , so we’ll need to rework it
De plus, les spécifications sont faciles à trouver.
Règle de la colonne d’oeil: M SK1 du temps de développement.
Pour une fonction hebdomadaire de 2-, les jours suivants sont indiqués sur la spécification Pour une fonction hebdomadaire de 1-:une demi-journée sur le specM SK2 Pour une fonction 2-journéeM SK1 une heure ou deux sur le spec.
Mais ne soyez pas religieux à cet égard.
Si vous' consacrez plus de temps à la spécification qu’à sa mise en oeuvre, vous ' l’excèdez dans vos réflexionsM SK3 Rappelez-vous que les spécifications sont des outils qui vous aident à travailler
Étant donné que l’estimation du logiciel est fondamentalement difficile. C’est là la vérité incommode ' Les estimations ne fonctionnent que si vous avez fait EXACTEMENT cette tâche avant la dernière dans cet environnement.
Ce qui ne se produit presque jamais.
Chaque fois que vous estimez la valeur de l’employé(e) :
C’est pourquoi:
Plus le travail est nouveau, plus les estimations sont mauvaises. Établir la même forme de CRUD que vous ' vous avez construite MSC3 foisM SK4 Vous ' vous serez proches. Intégration avec un nouveau service à l’aide d’un protocole inconnuMNK7 Votre estimation est une supposition entourée d’espoirMMK8
C'est pourquoi les spécifications doivent être claires.
Ils ont besoin de critères différents "doneM SK1critères. Au lieu de "feature X fonctionneMST4 ilMSC5s "nousMSS7on a répondu à la question YMSSS8
Exemple de spécifications pour l'exploration:
Le temps-la boxing est cruciale pour l’exploration . Sans elle, les tâches de recherche ne se terminent jamais.
Commencez par ce que vous savez:
Marquez les sections comme suit : "TBD." Soyez honnête en ce qui concerne l’incertitude
Utilisez ensuite le processus d’examen des spécifications pour combler les lacunes.
Rappelez-vous: incomplèteM SK1mais -honest beats complete-butMST4falseMSC5
Absolutement. La spécification n’est pas requise ' ne doit pas être un document distinct. Une émission écrite de GitHub ou d’un billet JIRA peut servir comme spécifications parfaitement bienM SK4
Ce qui importe, c’est le contenu.
Avantages de l’utilisation des émissions:
Conseils pour utiliser les questions comme spécifications:
L’essai: pourrait-on lire le problème et savoir ce qu’il faut construire , ce que " faitMSC3 signifieM SK4 et ce quiMST5 est hors de portéeM ST6 Si ouiM st7 c’est une bonne spécification indépendamment du formatMst9
Si vous travaillez dans les secteurs de la santé, des finances, de l’aérospatiale ou d’autres domaines réglementés, il se peut que vous ayez besoin de spécifications plus formelles pour assurer votre conformité.
Mais vous devrez aussi
Même dans des environnements réglementés, la spécification agile fonctionne. vous n’avez qu’un plus grand nombre de boucles à franchir . la spec est toujours un outilM SK3 c’est-à-dire ' il s’agit simplement d’un outil qui doit satisfaire les organismes de réglementation ainsi que les développeurs
La rédaction de bonnes spécifications de fonctions dans un environnement agile est une compétence qui s’améliore avec la pratique.
Principes clés:
L’élément le plus difficile est de ne pas écrire la spécification initiale. Il faut savoir quand cesser d’utiliser une fonction.
C’est pourquoi les estimations agiles sont si difficiles.
Le meilleur que vous pouvez faire: être clair sur ce qu'il faut M SK1 faire " signifier, le tempsMST4 l'incertitude de la boîteMSSK5 et mettre à jour la spécification comme vous l'aviez apprise.
Une bonne spécification permet aux développeurs de résoudre les problèmes avec intelligence tout en sachant exactement quand ils peuvent s’arrêter.
Et si vous êtes un développeur qui lit une spécification qui n’a pas de sens ou qui ne possède aucun critère clair " a fait " Critères : s’exprime, . Il n’est pas difficile d’utiliser ' il n’y a pas de difficulté à utiliser ; il est professionnel ' Il vaut mieux le trier maintenant que de construire une fonctionnalité qui continue de croître jusqu’à ce qu’elle prenne en charge l’application entière
© 2026 Scott Galloway — Unlicense — All content and source code on this site is free to use, copy, modify, and sell.