Écrire des user stories d'intégration que les ingénieurs peuvent construire

Un ingénieur prend un ticket qui dit "construire l'intégration Salesforce" et le fixe. Construire quoi, exactement ? Synchroniser quels objets, dans quelle direction, déclenchés par quoi, et comment sait-on quand c'est fini ? Alors il devine, construit une version plausible, la démontre, et entend le responsable partenariats dire "non, ce n'est pas ce dont le client a besoin". Deux semaines sont parties, et le vrai problème n'a jamais été le code. C'était que personne n'a traduit un objectif de partenariat vague en quelque chose qu'un ingénieur pouvait réellement construire et qu'un propriétaire pouvait réellement accepter.

Les user stories d'intégration sont cette traduction. Une user story décrit une fonctionnalité du point de vue de la personne qui l'utilisera : qui elle est, ce qu'elle veut faire, et pourquoi ça compte pour elle. Pour une intégration, ce cadrage fait quelque chose de précis et de précieux : il ramène la conversation vers le parcours du client, loin de la tentation interne de décrire l'intégration comme une liste d'endpoints à câbler ensemble. Une bonne user story d'intégration dit à un ingénieur quoi construire en lui disant à qui c'est destiné et à quoi ressemble le succès pour cette personne.

Ce guide porte sur écrire ces stories correctement pour un build partenaire. Nous couvrons ce qu'est une user story et pourquoi le cadrage client compte davantage pour les intégrations que pour les fonctionnalités internes, le fait qu'une intégration a deux côtés et que chacun a besoin de ses propres stories, le format qui rend une story prête pour l'acceptation, des exemples concrets que vous pouvez adapter, et les erreurs qui produisent des stories que les ingénieurs ne peuvent pas construire. À la fin, vous obtenez un format de story et un ensemble d'exemples que vous pouvez reprendre dans votre propre backlog.

L'essentiel en 60 secondes

Si vous ne lisez qu'une section, lisez celle-ci :

• Une user story est une fonctionnalité décrite du point de vue de l'utilisateur : qui il est, ce qu'il veut, et pourquoi. Pour les intégrations, l'"utilisateur" est un client de l'un ou des deux produits, pas votre ingénieur.
• Le cadrage client bat le cadrage endpoint. "En tant que commercial, je veux que les nouveaux contacts apparaissent automatiquement dans mon CRM" dit à un ingénieur quoi construire ; "appeler l'endpoint contacts" lui dit quoi taper sans dire pourquoi.
• Une intégration a deux côtés, et chacun a besoin de ses propres stories. Le client utilisant le produit A et le client utilisant le produit B veulent souvent des choses différentes de la même intégration. Écrivez pour les deux.
• Une story n'est pas prête pour l'acceptation tant qu'elle ne nomme pas le résultat. Le rôle et l'action ne suffisent pas ; la story doit dire ce qui doit être vrai pour que le client la considère comme finie.
• Les bonnes stories sont petites et indépendantes. Une story, un parcours. Une story qui couvre trois parcours est un épic, et un ingénieur ne peut pas l'estimer ni la terminer proprement.
• La story met en place les critères d'acceptation, elle ne les remplace pas. La story dit qui et pourquoi ; les critères disent exactement ce que "fini" veut dire, ce qui est un document distinct et plus serré.

Ce qu'est une user story, et pourquoi le cadrage client compte pour les intégrations

Une user story est une courte description d'une fonctionnalité écrite du point de vue de la personne qui l'utilisera. La forme conventionnelle est une phrase : en tant que [rôle], je veux [une action], afin de [un résultat]. Le format user story vient du développement logiciel agile, où tout son objectif est de garder l'équipe concentrée sur le besoin d'un utilisateur plutôt que sur une liste de tâches techniques. Il est délibérément non technique, car il décrit le quoi et le pourquoi et laisse le comment aux ingénieurs qui le construiront.

Pour une intégration, ce cadrage n'est pas juste une bonne pratique, c'est un correctif. La façon naturelle de décrire une intégration en interne est comme de la plomberie : "connecter notre webhook à leur API contacts et mapper ces champs". Cette description n'est pas fausse, mais elle est dangereuse, car elle laisse l'équipe construire quelque chose de techniquement complet qui ne résout aucun parcours client réel. Une intégration qui synchronise les contacts sans faute mais synchronise la mauvaise direction, ou au mauvais moment, ou sans le champ dont le client a réellement besoin, passe chaque vérification technique et échoue au seul test qui compte. Le cadrage client force la question que le cadrage plomberie saute : à qui c'est destiné, et qu'essaie-t-il d'accomplir ?

Cette question est pourquoi les user stories comptent davantage pour les intégrations que pour beaucoup de fonctionnalités internes. Une fonctionnalité interne a généralement un utilisateur évident, votre propre client, et l'équipe comprend déjà bien cet utilisateur. Une intégration a des clients des deux côtés qui peuvent l'utiliser pour des raisons différentes, et elle vit à la couture entre deux produits où il est facile de perdre entièrement l'humain de vue et de ne penser qu'aux données circulant entre les systèmes. La story ramène l'humain à la vue. Le travail en amont de définir ce que l'intégration devrait même faire vit dans le document de périmètre d'intégration ; les user stories sont comment ce périmètre se transforme en pièces buildables et testables.

Les deux côtés d'une intégration, et pourquoi chacun a besoin de ses propres stories

Voici ce qui fait trébucher les équipes nouvelles au travail d'intégration : une intégration n'est pas une fonctionnalité avec un utilisateur. Elle connecte deux produits, et chaque produit a ses propres clients qui vivent l'intégration différemment et veulent souvent des choses différentes d'elle. Si vous écrivez des stories depuis un seul côté, vous construisez une intégration qui sert bien un ensemble d'utilisateurs et laisse l'autre côté se demander pourquoi elle ne fait pas ce dont il a besoin.

Considérez une intégration entre un outil de support et un CRM. Le client de l'outil de support, un agent de support, veut que le contexte client du CRM apparaisse dans son ticket de support, pour aider sans changer d'onglet. Le client du CRM, un commercial, veut que les interactions de support apparaissent sur la fiche client, pour connaître les problèmes ouverts avant un appel de renouvellement. Même intégration, deux jobs entièrement différents, deux utilisateurs différents, deux définitions de fini différentes. Une équipe qui n'écrit que les stories de l'agent de support livre quelque chose que le commercial trouve inutile, et vice versa.

La discipline est d'énumérer les rôles utilisateurs des deux côtés avant d'écrire une seule story, puis d'écrire des stories pour chaque rôle qui a un vrai job. Toutes les intégrations ne sont pas symétriques, parfois un côté est clairement l'utilisateur principal et l'autre a juste besoin que les données affluent, mais vous ne le savez qu'après avoir regardé les deux côtés délibérément. C'est la même pensée des deux côtés qu'exige une proposition de valeur commune ; l'intégration existe pour servir un parcours partagé, et notre guide sur la proposition de valeur commune couvre comment cadrer ce parcours partagé avant de le décomposer en stories.

Le format qui rend une story prête pour l'acceptation

Une user story qui s'arrête à "en tant que rôle, je veux une action" est un début, mais ce n'est pas encore quelque chose qu'un ingénieur peut construire avec confiance, car elle ne dit pas à quoi ressemble le succès. Une story prête pour l'acceptation associe la phrase de la story à assez de contexte pour que la personne qui accepte le travail sache exactement ce que "fini" veut dire. La story nomme le qui et le pourquoi ; la version prête pour l'acceptation ajoute les conditions qui la rendent vérifiable.

La checklist de qualité classique pour une story est le mnémonique INVEST : une bonne story est Indépendante, Négociable, Valuable (de valeur), Estimable, Small (petite), et Testable. Deux de ceux-là comptent le plus pour les intégrations. Petite garde une story à un parcours, pour qu'un ingénieur puisse la construire et la finir proprement au lieu de se noyer dans une story qui contient secrètement cinq fonctionnalités. Testable signifie que la story a un pass ou fail clair, ce qui est le pont vers les critères d'acceptation, car une story que vous ne pouvez pas tester est une story que vous ne pouvez pas accepter.

L'accroche d'acceptation de cette dernière ligne est la couture entre la story et les critères d'acceptation. La story reste lisible et humaine ; les critères deviennent précis et testables. Les garder comme documents distincts compte : la story est ce dont vous discutez avec le partenaire et le client, les critères sont ce contre quoi l'ingénieur et la QA vérifient. Confondre les deux produit soit une story si détaillée que personne ne veut la lire, soit des critères si vagues que personne ne peut les tester. La discipline complète d'écrire des conditions vérifiables est un sujet à part entière, couvert dans critères d'acceptation d'intégration ; la story est ce à quoi ces critères s'attachent. Un pont utile de la story au test est un scénario de tâche, qui cadre une chose réaliste qu'un utilisateur essaie d'accomplir, et le guide du Nielsen Norman Group sur l'écriture de scénarios de tâche est un bon modèle pour garder ce scénario centré sur le but de l'utilisateur plutôt que sur l'interface.

Des exemples concrets que vous pouvez adapter

Des règles abstraites sur les stories sont faciles à approuver et difficiles à appliquer, alors voici des user stories d'intégration écrites comme elles devraient apparaître dans un vrai backlog. Remarquez que chacune nomme un rôle précis, une action unique, et un résultat concret, et qu'elles viennent en paires ou en ensembles couvrant les deux côtés de l'intégration. Traitez-les comme des modèles pour la forme, pas le contenu ; vos rôles et parcours différeront.

Une intégration de synchronisation CRM. Côté commercial : "En tant que commercial, je veux que les nouveaux leads captés dans l'outil marketing apparaissent dans mon CRM en moins d'une minute, afin de relancer pendant que le lead est encore chaud." Côté marketing : "En tant que responsable marketing, je veux que les stades de deal du CRM refluent vers l'outil marketing, afin d'arrêter d'e-mailer les leads que le commercial a déjà signés." Deux rôles, deux directions, deux résultats clairs, et chacun est un parcours unique et testable.

Une intégration support-et-CRM. Côté agent : "En tant qu'agent de support, je veux que le plan et le propriétaire du compte du client s'affichent en haut de chaque ticket, afin de prioriser et router sans quitter l'outil de support." Côté commercial : "En tant qu'account manager, je veux voir les tickets de support ouverts d'un client sur sa fiche, afin d'arriver à un appel de renouvellement en connaissant déjà ses problèmes." Même intégration, utilisateurs opposés, et aucune story ne serait complète sans l'autre.

Une intégration data-warehouse. "En tant qu'analyste de données, je veux que les événements de notre produit soient exportés vers le warehouse chaque heure, afin de les joindre aux données de facturation dans mes propres requêtes." Celle-ci est largement à sens unique, l'analyste est l'utilisateur principal et le produit source a juste besoin d'émettre des données propres, ce qui est correct. Toutes les intégrations ne sont pas symétriques, et forcer une story du second côté là où il n'y en a aucune ne fait qu'encombrer le backlog.

Un mot sur la discipline de périmètre à l'intérieur de ceux-ci. Chaque exemple est délibérément un parcours. Dès qu'une story se lit "en tant que commercial, je veux que les leads se synchronisent et les deals se synchronisent et les activités se synchronisent", elle est devenue trois stories portant une phrase, et un ingénieur ne peut pas l'estimer, la construire par incréments, ou l'accepter en morceaux. Découpez sur les coutures, un parcours par story, et le backlog reste buildable. Cette décomposition fait partie d'une bonne gestion de projet d'intégration, qui transforme un tas de stories en un plan séquencé.

Erreurs fréquentes, et comment les corriger

Cadrer la story comme un endpoint au lieu d'un parcours. La correction : réécrivez-la du point de vue du client. "Appeler l'API contacts" est une tâche ; "en tant que commercial, je veux les nouveaux contacts dans mon CRM automatiquement" est une story qui dit pourquoi la tâche existe. L'endpoint est le comment, et le comment appartient à l'ingénieur, pas à la story.

Écrire des stories pour un seul côté de l'intégration. La correction : énumérez d'abord les rôles utilisateurs des deux produits, puis écrivez une story pour chaque rôle qui a un vrai job. Une intégration construite à partir des stories d'un seul côté sert un ensemble d'utilisateurs et échoue discrètement l'autre, et vous le découvrez au lancement au lieu de la planification.

Entasser plusieurs parcours dans une story. La correction : découpez jusqu'à ce que chaque story soit un rôle, une action, un résultat. Une story qui couvre trois parcours ne peut être estimée, construite par incréments, ou acceptée proprement. Petite n'est pas un agrément ; c'est ce qui rend la story buildable et testable tout court.

S'arrêter à la story et sauter l'accroche d'acceptation. La correction : pour chaque story, écrivez ce qui doit être vrai pour que le client la dise finie, ce qui devient la graine des critères d'acceptation. Une story sans résultat testable est un souhait, et un ingénieur qui construit face à un souhait devine.

Traiter la story comme la spec complète. La correction : gardez la story humaine et lisible et laissez les critères d'acceptation porter les conditions précises et testables. Surcharger la story de détail technique la rend illisible pour la conversation partenaire, tandis que laisser de côté les critères la rend inbuildable pour l'ingénieur. Ce sont deux documents à dessein.

FAQ

Qu'est-ce qu'une user story d'intégration ? C'est une courte description d'une fonctionnalité d'intégration écrite du point de vue du client qui l'utilisera : en tant que [rôle], je veux [une action], afin de [un résultat]. Pour une intégration, l'utilisateur est un client de l'un ou des deux produits connectés, pas votre propre ingénieur, et le travail de la story est de dire à qui l'intégration est destinée et à quoi ressemble le succès pour cette personne.

Pourquoi cadrer le travail d'intégration en user stories plutôt qu'en tâches techniques ? Parce qu'une liste de tâches techniques laisse l'équipe construire quelque chose de techniquement complet qui ne résout aucun parcours réel. "Synchroniser l'endpoint contacts" peut être entièrement fait tout en synchronisant la mauvaise direction ou les mauvaises données. Le cadrage client force la question que le cadrage tâche saute, à qui c'est destiné et qu'essaie-t-il d'accomplir, qui est le seul test qui compte au bout du compte.

Pourquoi une intégration a-t-elle besoin de stories pour les deux côtés ? Parce qu'une intégration connecte deux produits, chacun avec ses propres clients qui l'utilisent pour des raisons différentes. L'agent de support veut le contexte CRM dans son ticket ; le commercial veut l'historique de support sur la fiche client. Même intégration, deux jobs différents. Écrire des stories pour un seul côté livre quelque chose qui sert ces utilisateurs et laisse l'autre côté sans ce dont il a besoin.

Qu'est-ce qui rend une user story prête pour l'acceptation ? Elle nomme non seulement le rôle et l'action mais le résultat qui vous dit que ça a marché, et elle est assez petite et testable pour avoir un pass ou fail clair. Les qualités INVEST aident : indépendante, négociable, de valeur, estimable, petite, et testable. Petite la garde à un parcours ; testable est ce qui laisse les critères d'acceptation s'attacher et la QA la vérifier.

En quoi une user story diffère-t-elle des critères d'acceptation ? La story est la description lisible et humaine de qui veut quoi et pourquoi ; les critères d'acceptation sont les conditions précises et testables qui définissent le fini. La story est ce dont vous discutez avec le partenaire et le client ; les critères sont ce contre quoi l'ingénieur et la QA vérifient. Ce sont des documents distincts, et les confondre produit soit une story illisible, soit des critères intestables.

Quelle taille devrait faire une user story d'intégration ? Un rôle, une action, un résultat, ce qui signifie généralement un parcours. Si une story se lit "synchroniser les leads et les deals et les activités", c'est trois stories en une phrase et elle ne peut être estimée ni construite par incréments. Découpez sur les coutures de parcours jusqu'à ce que chaque story soit quelque chose qu'un ingénieur peut construire et accepter seul.

Et si l'intégration ne sert vraiment qu'un côté ? Alors écrivez les stories pour ce côté et ne forcez pas une story du second côté qui n'a aucun vrai job derrière elle. Toutes les intégrations ne sont pas symétriques ; parfois un produit est l'utilisateur principal et l'autre a juste besoin d'émettre des données propres. La discipline est de regarder les deux côtés délibérément, pas d'inventer des stories pour que le backlog paraisse équilibré.

Pour aller plus loin

• Wikipédia, user story, sur le format rôle-action-résultat et son origine dans le développement agile.
• Wikipédia, mnémonique INVEST, sur les qualités qui rendent une story indépendante, petite et testable.
• Wikipédia, tests d'acceptation, sur la vérification qu'un build répond au besoin de l'utilisateur, où mène une story.
• Nielsen Norman Group, les scénarios de tâche en test d'utilisabilité, sur cadrer un but utilisateur réaliste plutôt qu'une action d'interface.

En bref

Les user stories d'intégration traduisent un objectif de partenariat vague en quelque chose qu'un ingénieur peut construire et qu'un propriétaire peut accepter. Une story décrit la fonctionnalité du point de vue du client, en tant que rôle, je veux une action, afin d'un résultat, ce qui force l'équipe à penser au parcours plutôt qu'à la plomberie. Ce cadrage compte davantage pour les intégrations que pour les fonctionnalités internes, car une intégration vit à la couture entre deux produits et il est facile de ne penser qu'aux données et d'oublier l'humain.

Écrivez des stories pour les deux côtés de l'intégration, puisque les clients de chaque produit la vivent différemment et veulent des choses différentes. Gardez chaque story petite et testable, un rôle, une action, un résultat, et associez-la au résultat qui vous dit que ça a marché, ce qui devient la graine des critères d'acceptation. Gardez la story humaine et lisible et laissez les critères porter les conditions précises et testables, car ce sont deux documents faisant deux jobs.

Si vous voulez que tout le chemin soit pris en charge, de la stratégie partenaire et d'une API prête pour les partenaires jusqu'à un travail d'intégration bien périmétré et bien storié, au lancement et à l'adoption, c'est exactement à cela que sert un audit partenaire. Nous étudions votre produit, votre API et votre potentiel de partenariats, puis définissons quoi construire, à qui c'est destiné, et comment livrer et prouver ensemble.