Tenir un journal de décisions dans Jira : se souvenir des raisons du choix

Six semaines après une version, quelqu’un demande pourquoi l’équipe a choisi les notifications par e-mail plutôt qu’un récapitulatif quotidien. Les tickets Jira expliquent ce qui a été construit. Un commentaire dit « convenu en planification ». Les personnes qui se souviennent de la discussion sont occupées et personne ne sait quelle contrainte a réellement pesé.

Un journal de décisions comble ce manque. Il conserve la situation, les options, le choix et ses conséquences à un endroit facile à retrouver. Avec le Decision Log de Power Pack, cette fiche se trouve à côté d’un ticket Jira, près du travail qu’elle explique.

Ce guide suit une équipe fictive de portail client qui rédige une fiche utile, la relie à la réalisation et la réexamine lorsque les besoins des clients évoluent.

Déterminez ce qui mérite une fiche

Un journal de décisions n’a pas besoin de consigner chaque conversation. Commencez par les choix que de futurs collègues pourraient légitimement questionner : une approche de réalisation, une dépendance, le périmètre d’une version ou un compromis délibéré dont les conséquences dépassent une petite tâche.

Pour notre équipe, l’envoi des notifications mérite une fiche. Le choix de l’e-mail immédiat influence réalisation, tests, instructions de support et attentes des clients. L’équipe a envisagé des alternatives et prévoit de reconsidérer le choix si le volume de messages augmente.

En revanche, corriger une faute dans le libellé d’un bouton ne nécessite probablement pas de fiche. La distinction est pratique : comprendre les raisons aiderait-il quelqu’un à maintenir, modifier ou expliquer le résultat plus tard ?

Les fiches de décision d’architecture, souvent appelées ADR, constituent un précédent utile. L’article original de Michael Nygard décrit de courts documents conservant contexte, décision, statut et conséquences, avec les décisions remplacées et une référence au nouveau choix. La source figure ci-dessous. Notre exemple applique cette idée légère à une décision de réalisation dans Jira.

Donnez à la décision un emplacement clair

Choisissez le ticket Jira qui représente le mieux le travail concerné. Ici, l’équipe utilise celui qui coordonne les notifications du portail client. Il renvoie déjà vers les tâches de développement et de test.

Indiquez à l’équipe où se trouve la fiche. Le Decision Log de Power Pack appartient à un ticket : adoptez une habitude simple pour le retrouver. Une note dans le ticket de coordination peut préciser que les décisions de notification y sont conservées. Si votre équipe possède un index de projet distinct, ajoutez-y le ticket selon votre processus habituel.

Évitez de disperser des copies sur plusieurs tickets en espérant qu’elles resteront cohérentes. Les autres tickets peuvent renvoyer vers l’emplacement choisi. Les exports sont utiles pour discuter, mais l’équipe doit savoir quelle fiche consulter pour connaître la position actuelle.

Écrivez le contexte avant la conclusion

Le contexte explique pourquoi la question se pose. Il doit distinguer faits, contraintes et hypothèses afin qu’un futur lecteur identifie ce qui a changé.

L’équipe écrit : « Les clients doivent savoir lorsqu’une demande de support change de manière significative. Le service actuel envoie déjà des e-mails. La première version du portail ne comprend pas de boîte de réception. Nous prévoyons peu de changements de statut visibles par le client pour la plupart des demandes, mais nous n’avons pas encore mesuré le volume de notifications après lancement. »

Ce paragraphe est plus utile que « l’e-mail est l’option la plus simple ». Il explique le point de départ et rend une hypothèse visible. Il évite aussi de prétendre que l’e-mail sera toujours le bon canal.

Ajoutez au besoin des références aux investigations. Si une exploration technique a éclairé le choix, indiquez le ticket contenant ses conclusions. Si les retours clients comptent, résumez la tendance pertinente sans copier inutilement d’informations privées dans la fiche.

Le contexte doit permettre à un nouveau collègue de comprendre la situation sans reconstituer toute une réunion. Gardez les détails qui influencent le choix et laissez les échanges sans rapport à leur emplacement d’origine.

Comparez de véritables alternatives

Une fiche utile montre ce que l’équipe aurait pu faire. Incluez les alternatives sérieusement envisagées, avec un avantage et un inconvénient honnêtes pour chacune.

Ces appréciations illustrent ce système fictif. Une autre équipe dispose peut-être déjà d’une boîte de réception ou d’un service de récapitulatif, ce qui changerait complètement le comparatif. Une bonne rédaction rend cette dépendance au contexte explicite.

Ne dévalorisez pas les options rejetées pour rendre le choix inévitable. Un récapitulatif offre un véritable avantage : moins de messages séparés. L’équipe l’écarte pour cette version parce que le calendrier et le périmètre de réalisation pèsent davantage dans les hypothèses actuelles.

Distinguez également une option d’une décision séparée. L’affichage du message complet d’un client dans un e-mail peut nécessiter sa propre revue. Regrouper toutes les questions de notification dans une fiche rend difficile de comprendre ce qui a réellement été convenu.

Énoncez le choix et ses conséquences

Rédigez une phrase complète : « Pour la première version du portail, nous enverrons un e-mail lorsqu’une demande de support subit un changement de statut significatif visible par le client. Les modifications internes ne déclencheront pas de message. »

Expliquez ensuite pourquoi : « Cela utilise le canal d’envoi existant et informe rapidement les clients des progrès tout en gardant un périmètre de version maîtrisable. » Cette phrase justifie l’exemple ; elle ne prétend pas que l’e-mail est toujours moins cher ou plus fiable.

Les conséquences méritent autant d’attention. L’équipe doit partager une définition du changement significatif. Les tests doivent couvrir les mises à jour répétées et les doublons. Le support doit expliquer quels événements produisent des messages. Les clients ayant des demandes actives peuvent encore recevoir plus d’e-mails qu’ils ne le souhaitent.

Une conséquence utile mène naturellement à du travail complémentaire. Consignez l’implication ici, puis gérez la tâche dans Jira. Une fiche doit aider à découvrir pourquoi un travail est nécessaire sans devenir un second backlog avec des statuts et responsables concurrents.

Créez la fiche dans Power Pack

Ouvrez Power Pack sur le ticket concerné et utilisez Decision Log (ADR Lite). Ajoutez une entrée dont le titre nomme le choix réel, par exemple « Utiliser l’e-mail immédiat pour les mises à jour courantes du portail ».

Choisissez une catégorie adaptée à l’équipe et commencez avec Proposed tant que le résultat reste en discussion. Ajoutez le décideur puis, une fois le choix fait, la date de décision. Le champ du décideur indique la responsabilité ; saisir un nom n’exécute pas un processus d’approbation à votre place.

Renseignez le contexte, les alternatives avec leurs avantages et inconvénients, sélectionnez l’option retenue et écrivez les conséquences. Rendez le contenu compréhensible pour quelqu’un qui n’a pas assisté à la discussion.

Ajoutez les clés Jira concernées si elles sont utiles. L’éditeur accepte des références séparées par des virgules pour identifier les tickets de développement et de test touchés. Ce sont des références consignées ; utilisez séparément le mécanisme normal de liaison de Jira si une relation entre tickets est nécessaire.

Relisez la fiche avec les personnes concernées. Vérifiez que l’option choisie et l’explication concordent. Confirmez l’enregistrement avant de demander aux collègues de se fier à la dernière version, surtout si l’outil indique un état local ou hors ligne.

Utilisez le statut pour clarifier la position actuelle

Power Pack propose Proposed, Accepted, Rejected et Superseded. Convenez de leur usage afin qu’un lecteur distingue une idée en attente d’une décision qui guide déjà la réalisation.

Lorsque Maya, responsable produit, tranche sur les notifications, l’équipe consigne la date et marque la fiche Accepted. Ce statut décrit la position de la décision. Il ne prouve ni l’achèvement de la réalisation, ni la réussite des tests, ni l’autorisation de publier.

La même distinction compte pour Rejected. Si une proposition n’est pas adoptée, une brève explication peut éviter qu’une personne répète une investigation sans savoir qu’elle a déjà eu lieu. Préservez les raisons utiles même lorsqu’aucun ticket de réalisation ne suit.

Réexaminez une décision lorsque ses hypothèses changent

Imaginez qu’après lancement, le portail accueille des clients ayant beaucoup de demandes actives. Le support signale que certains reçoivent plusieurs e-mails courants par jour. C’est un contexte nouveau, directement lié à l’hypothèse initiale d’un faible volume de messages.

L’équipe ouvre l’ancienne fiche avant de proposer un changement. Elle peut ainsi distinguer un compromis raisonnable à l’époque de la question actuelle du produit. La décision existante explique le choix de l’e-mail immédiat ; elle n’interdit pas une meilleure approche dans d’autres conditions.

Créez une nouvelle fiche Proposed pour le récapitulatif quotidien. Power Pack permet de dupliquer une entrée en fiche Proposed pour fournir un point de départ. Vérifiez soigneusement chaque champ copié : anciennes hypothèses, dates et conséquences ne s’appliquent peut-être plus.

Lorsque le nouveau choix est accepté, marquez l’ancienne fiche Superseded et indiquez la décision de remplacement dans le champ prévu. Conservez les raisons d’origine lisibles au lieu de réécrire l’histoire comme si l’équipe avait toujours prévu un récapitulatif.

Il s’agit d’une pratique documentaire d’équipe. Les fiches restent modifiables : convenez de créer des remplacements pour les changements de fond et de réserver les modifications ordinaires aux corrections ou clarifications. Ne traitez pas le journal comme une piste d’audit immuable.

Rendez la fiche utile au quotidien

Consultez le journal lorsqu’une personne rejoint l’équipe, propose une refonte ou demande pourquoi un ticket contient une exigence inhabituelle. Recherche et filtres aident à retrouver une entrée dans le journal du ticket. Power Pack peut aussi exporter du Markdown au format ADR pour une revue ou un autre processus documentaire.

Avant de partager un export, vérifiez qu’il reflète l’entrée actuelle et indiquez le ticket où l’équipe la tient à jour. Un document téléchargé est un instantané ; les modifications ultérieures ne mettent pas à jour une copie déjà envoyée ailleurs.

Commencez par une décision récente que l’équipe pourrait réexaminer. Écrivez le contexte, les vraies alternatives, l’approche choisie et les conséquences. Placez cette fiche à côté du travail Jira dans Power Pack, puis faites-la lire à un collègue absent de la discussion. S’il peut expliquer pourquoi le choix était pertinent et ce qui justifierait de le changer, le journal remplit son rôle.

• Michael Nygard : documenter les décisions d’architecture