Issues

En mars 2024, je me suis demandé comment utiliser correctement les termes Epic, Issue, User Story, Goal, Job Story, Vision, Pitch, Feature, Task, Bug, Spike, Dette technique, Theme.

Voici quelques réflexions à ce propos.

Tout d'abord, tous les artefacts suivants sont des Issues : Epic, User Story, Job Story, Vision, Pitch, Feature, Bug, Spike, Task.

Ensuite, Feature, Bug, Spike et Dette technique indiquent la finalité de l'issue, définissant la nature du travail à réaliser.

User Story et Job Story sont des méthodes de formulation d'issues.

J'ai mis beaucoup de temps à réaliser que les termes Epic, Vision, Theme, Pitch, Goal et Task permettent d'indiquer le niveau d'imprécision d'un objectif.

Exemple allant du flou très prononcé à une version faiblement floue :

• Vision – Le niveau le plus large et abstrait, décrivant une aspiration à long terme.
• Theme – Une direction stratégique regroupant plusieurs objectifs ou Epics.
• Pitch – Une proposition d'idée ou une justification d'un projet, pouvant inclure des objectifs mais restant plus conceptuel.
• Goal – Un objectif spécifique à atteindre, souvent mesurable.
• Epic – Une grande fonctionnalité ou un ensemble de tâches qui contribuent à un objectif plus large.
• Task – Niveau le plus précis, une tâche est une unité de travail concrète et actionnable.

Une ou plusieurs Merge Requests constituent une réponse formelle, exprimée en code, parmi toutes les réponses possibles à une demande formulée dans une issue.
Seule cette réponse formelle, exprimée en code, est véritablement précise. Même l'issue, aussi détaillée soit-elle, conserve toujours une part de flou.

Attention tout de même : quand je dis qu'une issue de type Vision est floue, cela ne veut pas dire que son auteur peut bâcler sa rédaction.
Si, par exemple, la description est limitée à 500 mots, l'auteur doit exploiter au mieux cette limite pour présenter sa vision avec précision. L'objectif n'est pas de créer du flou volontairement, mais plutôt d'exprimer clairement un concept qui, par nature, comporte encore des zones d'incertitude à explorer.

Voici quelques exemples d'issue floue publiés ici :

• 2023-10-28_2008
• Projet 11 - "Première version d'un moteur web PKM"
• 2024-09-07_2240

Une issue, en tant que texte écrit, comporte une part inévitable d'ambiguïté et nécessite donc son auteur pour être défendue :

C’est que l’écriture, Phèdre, a, tout comme la peinture, un grave inconvénient. Les œuvres picturales paraissent comme vivantes ; mais, si tu les interroges, elles gardent un vénérable silence. Il en est de même des discours écrits. Tu croirais certes qu’ils parlent comme des personnes sensées ; mais, si tu veux leur demander de t’expliquer ce qu’ils disent, ils te répondent toujours la même chose. Une fois écrit, tout discours roule de tous côtés ; il tombe aussi bien chez ceux qui le comprennent que chez ceux pour lesquels il est sans intérêt ; il ne sait point à qui il faut parler, ni avec qui il est bon de se taire. S’il se voit méprisé ou injustement injurié, il a toujours besoin du secours de son père, car il n’est pas par lui-même capable de se défendre ni de se secourir.

Phèdre - Dialogue de Platon

Conséquence pratique de tout cela :

• L'auteur d'une issue doit être disponible et accorder du temps à la personne qui va implémenter son issue.
• La personne qui implémente cette issue doit accepter l'imprécision de cette issue. En posant des questions, le développeur doit aider l'auteur à rendre cette issue plus précise.
• L'auteur de l'issue doit accepter de recevoir une implémentation qui ne correspond pas exactement à sa vision… et dans ce cas, il doit soit l'accepter ou accorder plus de temps à cette issue afin d'effectuer plusieurs itérations de correction de l'implémentation.

Ces règles pratiques sont aussi valables lorsqu'une issue est déclinée dans des issues avec un niveau de précision supérieur. Par exemple, lors de la rédaction d'issues de type Epic à partir d'une issue de type Vision.

« Permettre à l'auteur de défendre son texte » ne signifie pas exclusivement un dialogue oral. Ce dialogue peut s'effectuer :

• Par chat synchrone ;
• Par commentaire d'issue asynchrone ;
• Par visioconférence ;
• etc

Je pense que le niveau de précision d'une issue détermine le mode de communication à privilégier. Pour les issues de haut niveau d'abstraction — très floues (Vision, Theme, Pitch), la communication orale se révèle généralement plus efficace, car elle permet des échanges dynamiques et immédiats sur des concepts abstraits.

En revanche, pour les issues plus précises (Tasks, certaines Features), je privilégie une approche asynchrone avec des questions écrites détaillées. Cette méthode offre à l'auteur le temps nécessaire pour réfléchir et affiner sa rédaction. Je ne recours à la communication orale que lorsque des problèmes de compréhension persistent malgré les échanges écrits, afin de débloquer rapidement la situation.

---

Je cherche des solutions pour bien indiquer le niveau de précision des issues que j'écris.

Voici quelques exemples d'introductions d'issues :

Cette issue est de type "vision", c'est donc normal qu'elle soit imprécise. Les zones d'ombre seront affinées progressivement dans des sous-issues spécifiques. Pour clarifier certains aspects, des échanges oraux pourront être organisés afin de répondre à vos questions et d'enrichir cette vision.

Autre exemple :

Cette issue a été rédigée avec un souci particulier de précision. Si vous identifiez des erreurs, des incohérences ou si certains points nécessitent des éclaircissements, n'hésitez pas à les signaler dans les commentaires. Pour toute difficulté de compréhension ou doute persistant, je reste disponible pour organiser une session en visioconférence afin de faciliter nos échanges.

J'ai du mal à bien définir le terme thème en gestion de projet logiciel.

Dans cette note, je vais décrire les deux définitions que je connais.

---

Voici une définition de Ken Rubin, auteur du livre Essential Scrum :

A collection of related user stories. A theme provides a convenient way to indicate that a set of stories have something in common, such as being in the same functional area.

Dans la section glossaire de Essential Scrum

Un Theme peut-être assigné à tout type d'issue, par exemple Epic ou User Story.

---

Les auteurs du livre Product Roadmaps Relaunched ont une autre définition de Theme :

As we’ve touched on, in the relaunched roadmapping process we use themes and subthemes to express customer needs. This is probably a new concept for many of you, so let’s define what we mean by these terms.

Themes are an organizational construct for defining what’s important to your customers at the present time.

...

So, again, themes and subthemes represent the needs and problems your product will solve for. A need is generally something the customer doesn’t have yet, whereas a problem is something that’s not working right (with the existing product, or whatever substitute they might currently be using). Even though these two terms suggest subtle differences, the important point is that both refer to a gap or pain in the customer’s experience. When identifying the themes and subthemes for your roadmap, remember to consider both needs and problems from all angles.

Jared Spool, paraphrasing our very own Bruce McCarthy, says, “Themes help teams stay focused without prematurely committing to a solution that may not be the best idea later on.” As Spool points out, it is important to focus most of the roadmapping effort on customer needs and problems because “the viability of a feature may shift dramatically, while the nature of an important customer problem will likely remain the same.”

Page 124 du livre Product Roadmaps Relaunched

Dans ce livre, un Theme représente un besoin client important à un instant donné.

---

D'après ce que j'ai compris, Product Roadmaps Relaunched adopte une définition plus restrictive du concept de thème que Essential Scrum. Dans Product Roadmaps Relaunched, un thème sert uniquement à décrire des fonctionnalités de façon imprécise.

Exemple tiré du livre Product Roadmaps Relaunched :

• Theme: Billing & payments
  • Subtheme: Billing & payments API integration
  • Subtheme: API integration testing

Pour résumer :

• Essential Scrum inclut des thèmes qui ne sont pas seulement liés aux fonctionnalités, mais aussi à la stratégie globale, à l’organisation, voire aux aspects techniques et processus internes.
• Product Roadmaps Relaunched reste focalisé sur l'expérience utilisateur et les besoins clients, avec des thèmes qui expriment des fonctionnalités sans trop rentrer dans les considérations techniques ou organisationnelles.

---

#JaiDécidé d'adopter la définition de "Theme" donnée dans Essential Scrum.

Lorsque vous collaborez avec moi, je préfère recevoir les extraits de vos textes Markdown, vos codes sources, et le contenu de votre terminal au format texte plutôt que sous forme de captures d'écran.

Voici ci-dessous six inconvénients liés à l'utilisation de captures d'écran.

1. Impossibilité de copier le contenu

Lorsque vous partagez des lignes de commande, des configurations ou des messages d'erreur en capture d'écran, je ne peux pas copier le contenu pour le tester ou effectuer des recherches. Cela m'oblige à ressaisir manuellement le texte, avec le risque d'introduire des erreurs.

De plus, il m'est impossible de citer précisément une partie de votre contenu lors de nos échanges.

2. Impossible de cliquer sur les liens

3. Recherche inefficace

Les outils comme GitHub, GitLab, Slack, Zulip, Mattermost, Signal, WhatsApp, ainsi que les moteurs de recherche dans les pages des navigateurs, ne permettent pas de rechercher du texte présent dans des images. Le format texte, en revanche, est entièrement indexable et facilitera la recherche d'informations.

4. Consommation de mémoire multipliée par 100

Les captures écrans consomment beaucoup plus d'espace disque que du texte.

Prenons l'exemple d'un extrait de terminal au format texte :

# docker info
Client: Docker Engine - Community
 Version:    27.1.2
 Context:    default
 Debug Mode: false
 Plugins:
  buildx: Docker Buildx (Docker Inc.)
    Version:  v0.16.2
    Path:     /usr/libexec/docker/cli-plugins/docker-buildx
  compose: Docker Compose (Docker Inc.)
    Version:  v2.29.1
    Path:     /usr/libexec/docker/cli-plugins/docker-compose

Server:
 Containers: 194
  Running: 194
  Paused: 0
  Stopped: 0
 Images: 34
 Server Version: 27.1.2
 Storage Driver: overlay2
  Backing Filesystem: extfs
  Supports d_type: true
  Using metacopy: false
  Native Overlay Diff: true
  userxattr: false
 Logging Driver: json-file
 Cgroup Driver: systemd
 Cgroup Version: 2

Cet extrait consomme 682 octets de mémoire.

Je viens de vérifier : une capture d'écran équivalente consomme 83 000 octets de mémoire, soit 121 fois plus d'espace disque qu'un simple extrait de texte. Pour ceux qui utilisent des écrans haute résolution, comme les écrans Retina, cette consommation peut même être multipliée par 4.

Il est regrettable de saturer 100 fois plus rapidement l'espace disque sur des services comme GitHub, GitLab, Slack, Zulip, Mattermost, etc., pour une expérience utilisateur finalement moins optimale.

5. Chargement moins rapide des pages

Ceci est surtout impactant pour les issues ou Merge Request avec beaucoup de commentaires.

6. Occupation excessive de l'espace écran

Les captures d'écran, en particulier celles prises sur des écrans Retina, occupent souvent un espace d'écran excessif dans la fenêtre du navigateur, rendant la lecture des commentaires plus difficile et nuisant à la fluidité de la navigation.

Je préfère ne pas utiliser le terme « ticket » pour traduire « issue » en anglais.
Il m'arrive cependant d'employer « ticket » uniquement pour désigner les demandes de support ou les bugs.

Les définitions proposées par le Wiktionary et Wikipedia semblent corroborer cette distinction :

« Billet comportant un numéro d’ordre de passage dans une file d’attente. »

-- définition wiktionary.

« Une demande d'assistance, désignées ainsi dans le métier de l'assistance sous le nom de ticket. »

-- wikipedia

Le terme anglais « issue » a une portée bien plus large que celle de « ticket ». Il peut désigner :

• Point à débattre
• Sujet à discuter
• Question Problème

ChatGPT me dit :

En français, le terme "issue" peut être traduit de différentes manières en fonction du contexte. Voici quelques traductions courantes :

• Problème : C'est la traduction la plus directe et souvent utilisée. Elle est appropriée si l'"issue" en question concerne un bug ou un défaut à corriger.
• Ticket : Ce terme est également couramment utilisé dans le contexte du suivi des tâches ou des bugs. Il est un peu plus neutre et peut désigner aussi bien un problème qu'une demande de fonctionnalité.
• Tâche : Si l'"issue" représente quelque chose à faire (comme une nouvelle fonctionnalité à développer), "tâche" peut être une bonne traduction.
• Demande : Ce terme peut être utilisé si l'"issue" est une requête ou une demande de changement.

En fonction du contexte précis, tu peux choisir le mot qui semble le plus approprié. Par exemple :

• Pour un bug : Problème ou Bug.
• Pour une nouvelle fonctionnalité : Tâche ou Demande.
• De manière générale, dans le cadre d'un système de gestion de projet : Ticket.

Le terme "issue" est parfois laissé tel quel en français dans certains contextes techniques, surtout dans des équipes habituées aux outils comme GitLab ou GitHub.