Les systèmes de suivi des problèmes tels que Redmine, Jira, GitHub ou GitLab ne sont pas simplement des outils administratifs. Ils définissent comment le travail passe par une équipe : ce qui est réparé, ce qui est reporté et ce qui se transforme en silence en dette technique. Dans de nombreuses équipes, les retards ne sont pas causés par des bogues difficiles, mais par des rapports de problèmes mal écrits.
Un rapport de problème faible oblige les autres à poser des questions de suivi, à deviner l’intention ou à abandonner entièrement la tâche. Un bon problème, d’autre part, permet à quelqu’un qui ne connaît pas le problème de le comprendre, de le reproduire et de vérifier la solution avec un minimum de va-et-vient.
Cet article aborde les erreurs les plus courantes dans les rapports de problèmes et explique comment les éviter. L’objectif est simple : rendre les problèmes exploitables, reproductibles et vérifiables.
Qu’est-ce qu’un problème (et pourquoi le type est important)
Un problème représente une unité de travail ou une unité de défaillance qui peut être suivie et résolue. Tous les problèmes ne sont pas des bogues, et tout traiter comme un bogue interrompt rapidement la priorisation et la planification.
- Bug / défaut : le comportement existant est incorrect ou cassé.
- Demande de fonctionnalité : une nouvelle fonctionnalité ou un nouveau comportement est souhaité.
- Tâche / Corvée : travaux de maintenance sans changement visible face à l’utilisateur.
- Question / Assistance : Une clarification est nécessaire, pas une modification de code.
- Documentation : documentation manquante, peu claire ou incorrecte.
Le choix du mauvais type crée du bruit. Les bugs sont en concurrence avec les questions, les tâches semblent urgentes lorsqu’elles ne le sont pas et de vrais défauts peuvent être enterrés.
Erreur 1 : titres vagues ou dénués de sens
Des titres tels que « bug », « ne fonctionne pas » ou « problème urgent » ne communiquent rien. Ils sont impossibles à rechercher, impossibles à trier et inutiles dans les rapports ou les tableaux de bord.
Une formule de titre pratique est : Composant + Symptôme + Contexte.
- Mauvais : « Problème de simulation »
- Mieux : « Le solveur de diffusion diverge lorsque DT > 1e-3 avec les limites de Neumann »
- Mauvais : « le graphique est rompu »
- Mieux : « La visionneuse de tracé ne se met pas à jour après un changement de paramètre pendant l’exécution »
Erreur 2 : étapes de reproduction manquantes ou incomplètes
Sans étapes de reproduction, un problème devient deviner. Même les problèmes réels sont souvent fermés car « ne peut pas se reproduire » simplement parce que le journaliste a ignoré les actions clés.
Les bonnes étapes de reproduction sont :
- minimal (seulement ce qui est nécessaire),
- commandé (étape par étape),
- répétable (conduire le même résultat).
« Ouvrir l’application et il plante » n’est pas un chemin de reproduction. « Exécutez la simulation avec NX=2000, DT=1E-3, puis activez le pas adaptatif » est.
Erreur 3 : aucun résultat attendu
De nombreux problèmes décrivent ce qui n’allait pas, mais n’expliquez jamais ce qui aurait dû se passer à la place. Sans résultat attendu, il n’y a pas de définition claire de « fixe ».
Le comportement attendu n’a pas besoin de théorie ou de justification. Une simple comparaison suffit :
- Attendu : la simulation reste stable et converge.
- Réel : les valeurs augmentent sans limite après 50 itérations.
Cette distinction transforme les plaintes subjectives en conditions vérifiables.
Erreur 4 : Aucune preuve ou artefact
Le texte seul est souvent insuffisant, en particulier pour les problèmes d’interface utilisateur, l’instabilité numérique ou les problèmes de performances.
Les preuves utiles peuvent inclure :
- messages d’erreur ou traces de pile,
- journaux avec horodatages,
- Captures d’écran ou courtes vidéos,
- Tracés montrant un comportement inattendu.
Évitez de vider les journaux bruts sans contexte. Mettez en évidence la section pertinente et expliquez pourquoi c’est important.
Erreur 5 : Informations sur l’environnement manquantes
« Travail sur ma machine » n’est pas un sarcasme, c’est une réalité. Le logiciel se comporte différemment selon les versions, les plates-formes et les configurations.
Au minimum, un problème devrait inclure :
- version d’application ou de bibliothèque,
- système d’exploitation,
- Runtime (version Python, compilateur, etc.).
Pour les logiciels de recherche ou de simulation, les détails de l’environnement incluent souvent également la taille du maillage, le pas de temps, le type de solveur, la tolérance et la graine aléatoire.
Erreur 6 : plusieurs problèmes dans un problème
Combiner des problèmes sans rapport avec un seul problème rend difficile l’attribution, la priorité ou la fermeture correcte.
Un problème doit correspondre à une cause racine ou à un mode de défaillance. Si des problèmes sont liés, ils peuvent être liés. Sinon, ils doivent être divisés.
Erreur 7 : Priorité ou gravité incorrecte
Tout déclarer « critique » élimine le sens de l’étiquette. La priorité doit refléter l’impact, et non la frustration.
Une approche utile consiste à décrire explicitement l’impact :
- Combien d’utilisateurs sont concernés ?
- Les données sont-elles corrompues ou perdues ?
- Ce bloc fonctionne-t-il davantage ?
Laissez l’équipe ou le propriétaire du produit attribuer la priorité en fonction de ces informations.
Erreur 8 : aucun exemple reproductible minimal
Les grands projets cachent souvent de petits bugs. Fournir un exemple minimal reproductible permet d’économiser des heures d’enquête.
Les exemples dépendent du contexte :
- Pour le code : un court extrait qui déclenche le problème.
- Pour les simulations : domaine minimal, paramètres et conditions aux limites.
- Pour l’interface utilisateur : test de compte, de données de test ou d’indicateur de fonctionnalité.
Erreur 9 : langage émotionnel ou accusateur
Des déclarations telles que « cela a été cassé à nouveau » ou « rien ne fonctionne » n’ajoute aucune valeur technique. Ils rendent également la collaboration plus difficile.
Le langage neutre reste concentré sur le système, pas sur les personnes. Décrivez le comportement, pas le blâme.
Erreur 10 : Problèmes sans critère de clôture clair
Un problème doit avoir une condition claire dans laquelle il peut être fermé. Sans cela, les correctifs sont subjectifs et les problèmes sont souvent rouverts.
Les critères de clôture peuvent être simples :
- Les tests passent,
- L’erreur n’apparaît plus,
- La sortie correspond à la référence attendue.
Liste de vérification rapide avant de soumettre un problème
- Le titre est-il spécifique et consultable ?
- Quelqu’un d’autre peut-il reproduire le problème ?
- Les résultats attendus et réels sont-ils clairement indiqués ?
- L’environnement est-il décrit ?
- Le problème ne décrit-il qu’un seul problème ?
Conclusion
Une question bien écrite n’est pas une bureaucratie. Il s’agit d’un investissement dans la clarté, la rapidité et la compréhension partagée.
Une règle d’or utile est la suivante : écrivez le problème comme si vous le répariez dans deux semaines, sans aucun souvenir du contexte d’aujourd’hui. Si le rapport est toujours logique, il est probablement assez bon.