Leadership en test : Documentation

Paul Gerrard

on Feb 3, 2026

QUICK SUMMARY

Note de l’éditeur : Bienvenue dans la série Leadership In Test proposée par l’expert en test logiciel et consultant Paul Gerrard. Cette série vise à aider les testeurs ayant quelques années d’expérience — en particulier ceux travaillant en équipes agiles — à exceller dans leurs rôles de responsable ou de manager du test. Dans l’article […]

TABLE OF CONTENTS La valeur de la documentation Les dangers des modèles et du copier-coller Types de documentation de test Conseils pour concevoir la documentation

Note de l’éditeur : Bienvenue dans la série Leadership In Test proposée par l’expert en test logiciel et consultant Paul Gerrard. Cette série vise à aider les testeurs ayant quelques années d’expérience — en particulier ceux travaillant en équipes agiles — à exceller dans leurs rôles de responsable ou de manager du test.

Dans l’article précédent, nous avons présenté un manifeste du risque destiné à aider les managers. Dans cet article, nous poserons la question traditionnelle : « Combien de tests sont suffisants ? ». Attention : la réponse dépend des parties prenantes.

Inscrivez-vous à la newsletter The QA Lead pour recevoir une alerte lorsque de nouveaux épisodes de la série sont publiés. Ces articles sont extraits du cours Leadership In Test de Paul Gerrard que nous vous recommandons vivement pour approfondir ce sujet et d’autres thématiques. Si vous vous inscrivez, utilisez notre code exclusif QALEADOFFER pour obtenir 60 $ de réduction sur le prix du cours complet !

Quel que soit le projet, l’organisation ou la démarche, la documentation trouve toujours sa place. Une bonne documentation est une bénédiction : elle fournit une trace utile de l’approche, du périmètre, des plans, des conceptions et des résultats d’analyse, de développement et des activités de test.

Dans cet article, je vais aborder :

La valeur de la documentation
Les dangers des modèles de documents et du copier/coller
Les types de documentation de test
Conseils pour concevoir la documentation

C’est parti.

La valeur de la documentation

Dans les projets structurés, les documents sont généralement considérés comme des livrables à part entière. Dans des environnements agiles ou continus, la documentation peut être produite comme sous-produit, avec une valeur variable.

La rédaction de documents constitue peut-être l’activité principale des rédacteurs techniques professionnels, mais pour la plupart des praticiens, c’est une corvée — quel que soit son intérêt. Même si la rédaction de documents peut sembler ennuyeuse à certains, le vrai problème réside dans le fait que, dans de nombreux contextes, la majorité de la documentation est tout simplement une perte de temps. Elle a peu de valeur, elle n’est pas à jour, elle est inexacte — ou les trois à la fois.

Tout responsable de test a rédigé des stratégies de test qui n’ont pas été lues ou adoptées. Les testeurs écrivent des tonnes de plans de test, de scénarios et de rapports, et le seul contenu utile aux parties prenantes est le résumé d’une page au début ou à la fin du document.

Nous avons tous rédigé des documents dont nous savons qu’ils ont peu de valeur et que personne ne lira.

Cela provient de problèmes courants de documentation rencontrés dans les projets, qu’ils soient petits ou grands. Pour chaque document que nous rédigeons, plusieurs questions doivent être posées :

Quel type de document ? Une politique ou une stratégie, une approche ou un plan, une conception ou une mise en œuvre, ou bien un résultat et une interprétation ?
Quel est l’objectif du document ?
Quels contenus sont nécessaires pour atteindre cet objectif ?
Quelles sources de connaissances faut-il mobiliser pour créer le contenu ?
Si le document doit évoluer dans le temps, comment sera-t-il maintenu ?
Quel niveau de détail est nécessaire ?

En tant que responsable de test ou en tant qu’équipe, il vous faudra déterminer quels types et formats de documentation sont appropriés et, s’il s’agit de traces précises ou de soi-disant documents vivants, comment ils seront maintenus à jour.

Les dangers des modèles de documents et du copier/coller

Si votre projet exige un type de document précis, comme un plan de tests système ou un registre des risques, il peut être tentant de chercher sur internet un modèle prêt à l’emploi pour ces documents (et bien d’autres types).

Certains modèles peuvent prétendre respecter une norme ou une convention, et avoir été téléchargés et utilisés des milliers de fois. Parfois, un modèle peut sembler correspondre exactement à votre besoin. Mais, comme nous allons le voir, même si la table des matières paraît complète, cela peut vous poser problème.

Il se peut aussi que vous-même ou d’autres membres de votre entreprise ayez rédigé un document similaire pour des projets précédents. Vous pourriez être tenté de copier ce document, de le renommer, d’actualiser les références à l’ancien projet et d’adapter le contenu.

Attention : D’après mon expérience d’auditeur indépendant, cela est très courant — et souvent un vrai problème.

Tout d'abord, il est généralement évident qu'un copier/coller ou une édition a été faite. Le langage utilisé dans le texte semble souvent déconnecté du projet et il y a des lacunes et des passages superflus partout. Pourquoi cela ?

Utiliser un modèle préétabli ou un document existant comme source comporte plusieurs risques :

Il paraît complet, mais peut inclure des sujets inappropriés et en omettre d'autres qui sont essentiels.
Il fournit des titres pour un document, mais absolument aucune indication sur le contenu approprié à chaque rubrique.
Il peut contenir du texte qui semble réutilisable et qui est copié tel quel d'un projet antérieur sans rapport, mais ce texte peut donner une mauvaise impression, être inexact ou incomplet.

Utiliser des modèles pour obtenir des titres et la mise en forme de base peut être utile, mais le principal problème des modèles est le suivant :

*Utiliser un modèle peut faire gagner du temps ; le risque, c’est de ne pas réfléchir suffisamment à la rédaction.*

La tentation avec les modèles est de leur accorder une confiance excessive puis de remplir les différentes sections avec du remplissage. Après tout, vous pouvez penser que le document ne sert qu’à cocher une case et que personne ne le lira. Le risque avec les modèles, c’est d’arrêter de réfléchir et de rédiger un document qui a peu de valeur.

Types de documentation de test

Dans cette section, nous examinerons les différentes formes de documentation de test et discuterons de certaines considérations dans les projets structurés ou agiles/continus par opposition à la méthode traditionnelle en cascade.

L’ensemble principal des documents de test a tendance à se regrouper dans les catégories suivantes :

Politique et stratégie (parfois appelées Plan Directeur de Test)
Définition de test (aussi appelée spécification ou plans de test, de manière confuse)
Conception de test
Cas de test
Procédures ou scripts de test
Exécution des tests
Planification
Journal
Rapport de test

La gamme ci-dessus de types de documents couvre la définition du processus de test, les principales activités de définition, d’exécution et de rapport.

Il existe plusieurs autres documents liés aux tests qui, dans des environnements plus bureaucratiques, incluraient les définitions et processus de gestion de l’environnement de test, les procédures d’acceptation, les processus de gestion des incidents, etc. (nous aborderons la gestion des incidents dans un prochain article).

Une autre omission évidente dans la liste ci-dessus serait un plan ou un calendrier global pour les activités de test. Un calendrier n’est pas vraiment un document de test, il s’agit d’un sous-ensemble du plan global du projet pour un projet structuré (nous aborderons également la planification du calendrier dans un prochain article, alors restez à l’écoute !).

Politique, stratégie, plan directeur de test

*Objectif*	Une politique couvre généralement une organisation entière et inclut un sous-ensemble de sujets s'appliquant à tous les projets. Une stratégie couvre généralement un seul projet (ou une seule application) Dans l'ensemble, la stratégie fournit les décisions prises concernant les questions logistiques d'approche, de transfert, de responsabilités, d'environnements, etc. Certaines de ces décisions peuvent être prises à l'avance et documentées dans la stratégie Certaines décisions ne peuvent pas être prises maintenant, mais la stratégie peut documenter le processus ou la méthode ou les informations permettant de prendre ces décisions (dans le projet) Pour les situations incertaines, ou les événements imprévus nécessitant des décisions, la stratégie documentera les principes généraux (ou le processus) à suivre.
*Contenu*	Parties prenantes, objectifs, principaux risques identifiés Principes/test ou approche à adopter, par exemple approche de test basée sur les risques Processus de test (étapes du test) : objectifs et périmètre critères d'acceptation méthodes, techniques livrables (documents) responsabilités activités de test non-fonctionnel/technique politique de gestion des fournisseurs (de test) processus de gestion d'incidents sources de données de test environnements de test stratégie d’outils/automatisation Formats de documentation/modèles
*Sources*	Parties prenantes, utilisateurs, analystes métier, développeurs, exploitants
*Maintenance*	En général, un document ponctuel défini pour un projet ou un programme
*Considérations Agiles/Continues* La stratégie de test pour les projets agiles utilisant Scrum, par exemple, sera probablement assez brève et ne comportera que quelques pages (si elle est documentée). Le processus de test peut ne pas comporter de phases, mais il y aura probablement une définition des tests à différents niveaux. Par exemple : Tests dans un sprint ou une itération Tests pour une livraison Tests d’intégration système (avec d’autres systèmes ou interfaces) Tests utilisateurs (dans le sprint et/ou au niveau de la livraison). La façon dont les outils sont utilisés lors des tests par les développeurs (et en utilisant BDD ou TDD par exemple) n’est probablement pas documentée, mais les équipes de développement sont censées faire évoluer une approche et collaborer avec les autres membres de l’équipe à mesure qu’elles valident du nouveau code. Le rôle du testeur peut être de tester les fonctionnalités de manière interactive à mesure qu’elles sont livrées par les développeurs, ou d’agir en tant que coach testing pour le reste de l’équipe. Comme pour l’utilisation des outils et/ou du TDD, la manière de travailler évoluera dans le temps et ne sera peut-être jamais documentée formellement.

Définition de test (conception, cas, procédures)

*Objectif*	Démontrer le flux ou la traçabilité entre les sources de connaissance et les tests à réaliser Documenter la couverture (contre plusieurs modèles) des aspects des exigences, des fonctionnalités système ou du comportement utilisateur Permettre aux parties prenantes de revoir le périmètre, l’approche, la couverture et les choix faits lors de la création des tests à appliquer Fournir des instructions pour l’exécution des tests à un niveau de détail convenu.
*Contenu*	Périmètre du test – à un haut niveau par exemple les fonctionnalités, et à un niveau inférieur, par exemple, les modèles de comportement Couverture des tests par rapport aux éléments couverts (par exemple, une matrice de couverture des exigences ou un autre modèle de test) Cas de test identifiant les fonctionnalités, pré-conditions, entrées et post-conditions (résultats attendus inclus) Procédures de test, réutilisables pour exécuter les cas de test sélectionnés.
*Sources*	Parties prenantes, utilisateurs, exigences, conceptions et spécifications
*Maintenance*	En principe, avec des exigences figées, il devrait y avoir une version validée de ces documents En cas de changement d’exigence ou de périmètre, les testeurs devront ajuster la documentation, maintenir les aspects traçables des documents et fournir une gestion de configuration ou un journal des modifications.
*Considérations Agiles/Continues* Le volet définition du test est celui où l’approche agile diffère le plus des projets structurés. Il est possible que les testeurs qui se concentrent sur les fonctionnalités livrées ne créent aucune documentation. Cela peut se justifier s’il existe une politique ou une charte de test généralisée pour les fonctionnalités, par exemple. Plus généralement, il y aurait une charte succincte décrivant les tests prévus pour chaque fonctionnalité lors d’une session de test exploratoire. Une charte est un plan pour une courte période d’exploration. Une charte identifiera typiquement : Le périmètre de la session – la ou les fonctionnalités à couvrir et/ou des fonctionnalités ou comportements spécifiques du système L’objectif de la session – explorer certains aspects de comportement, se focaliser sur un risque ou un mode de défaillance, appliquer des scénarios sélectionnés La durée de la session est généralement de 45 à 120 minutes. La session est nécessairement restreinte, mais les testeurs restent libres d’explorer hors périmètre si cela a de la valeur Une charte peut viser l’exploration – comprendre ce que fait une fonctionnalité, identifier les comportements spécifiques qui méritent d’être testés, estimer combien de sessions et de tests sont nécessaires pour valider une fonctionnalité complexe, déterminer quelles données de test seraient nécessaires, etc. Une charte peut cibler un test sur une fonctionnalité précise, mais mettre en avant des zones nécessitant plus d’attention que d’autres. Les outils BDD et les scénarios dans un format spécifique, par exemple des user stories formatées Cucumber ou Gherkin et des scénarios associés, peuvent apporter la traçabilité et le contenu attendus d’une conception et de procédures de tests. Chaque scénario avec des clauses « donné/quand/alors » indique pré-conditions, entrées et post-conditions. Ils sont liés à une fonctionnalité unique, fournissant ainsi un cas/procédure de test minimal et traçable aux fonctionnalités. Les tests scriptés pour être exécutés par des outils peuvent ou non faire l’objet d’une documentation intermédiaire. Les équipes se basent davantage sur l’observation des tests automatisés et les tableaux de jeux de données utilisés par les scripts automatisés que sur une documentation formalisée des conceptions de test.

Exécution des tests (planification, journal)

*Objectif*	Spécifier l'ordre de passage des tests Enregistrer le statut des tests — exécuté/non exécuté et statut Fournir les résultats d’exécution des tests pour le reporting
*Contenu*	Identifiant du test, testeur, date/heure d'exécution, statut Pour les tests présentant un comportement anormal (optionnellement) : Détails du test tel qu’exécuté si les détails diffèrent du script Résultat réel vs attendu Autres observations, interprétations Statut du test (défaut, anomalie de configuration ou d'environnement, etc.) ID du rapport d'observation ou de défaut (le cas échéant)
*Sources*	Inventaire des cas/procédures de test, testeurs
*Maintenance*	Le planning change en fonction du périmètre des tests et des procédures modifiées, supprimées ou ajoutées au plan. Les tests sont susceptibles d'être exécutés plusieurs fois, soit en tant que re-tests, soit en tant que tests de régression. Le journal doit conserver l'historique complet de tous les tests du périmètre.
*Considérations Agile/Continues* Si les projets agiles/continus ne s’engagent pas dans la rédaction de documents de définition de test, ils compensent en encourageant les testeurs à tenir des journaux plus précis de l'exécution des tests. Lorsque les tests sont réalisés lors de sessions basées sur des chartes, on s'attend à ce que le testeur prenne de bonnes notes sur les tests effectués. Il existe peu d’outils dédiés au suivi des tests, autres que des carnets de notes ; ainsi, beaucoup de testeurs utilisent des éditeurs de texte simples, des applications de prise de notes ou même des carnets papier. Les journaux servent principalement à consigner toutes les activités et observations significatives effectuées lors des sessions. Un journal typique de test exploratoire comprendrait par exemple : Structure des fonctionnalités explorées (cartographie du périmètre) Observations, questions relatives aux fonctionnalités explorées durant la session Modèles, listes, tableaux d’éléments de test et d’idées de tests Tests réalisés, consignés avec suffisamment de détails pour permettre leur reproduction Anomalies détectées — échecs, comportements douteux, lenteurs, mauvaise expérience utilisateur, etc. Temps passé sur l’exploration, la préparation, les tests, l’enquête, la consignation des défauts, la revalidation, la régression, et le temps non productif Date/heure de l’enregistrement Lorsque les testeurs consignent leurs activités dans des outils de prise de notes ou autres, ils emploient parfois un balisage ou un langage spécifique au domaine pour structurer leurs notes. Celles-ci peuvent être traitées par de simples outils internes pour générer des synthèses d’activités destinées au rapport de test. Les tests exécutés par des outils (qu'ils soient propriétaires ou open source) génèrent des journaux automatiquement. Généralement, ces journaux sont consultables par l'outil ou par des procédures écrites par l'utilisateur.

Rapport de test

*But*	Communiquer le résultat d'une étape de test, de tests sélectionnés ou d'une session de test Peut également s'appliquer aux exigences techniques ou aux activités de test non fonctionnelles, auquel cas le contenu diffère pour correspondre à l'objectif de test Informer partiellement les parties prenantes afin de leur permettre de prendre une décision sur l'acceptation ou la mise en production d'un système ou sous-système.
*Contenu*	Heures de début/fin du test et durée Environnement de test Version(s) du logiciel et du système testés Buts et périmètre des tests (issus de la stratégie de test, de la définition du test) Résumé narratif des résultats Fonctionnalités jugées conformes aux besoins Risques considérés comme traités Tests importants restants (échoués ou bloqués) Fonctionnalités partiellement testées ou non testées Risques partiellement ou non traités. Détails des résultats de test avec sortie des journaux de test, etc. Statut des plans de contournement pour les anomalies restantes Analyses de test Progression et état des tests au fil du temps Statistiques des incidents
*Sources*	Stratégie de test, définitions de test, journal de test, rapports d'incidents Une grande partie du contenu d'un rapport de test sera issue des outils utilisés pour enregistrer les définitions de test, le journal de test et le journal d'incidents ou de défauts.
*Maintenance*	Il s'agit d'un instantané pour une phase d'exécution de test et il n'est pas maintenu par la suite.
*Considérations Agile/Continues* Le but d’un rapport de test dans un projet agile peut concerner une itération ou un sprint individuel, des tests pour une version, ou une phase de test de niveau supérieur telle que l’intégration ou l’acceptation globale du système. Peu importe le cas, le but ne change pas. Une grande partie du contenu d’un rapport de test provient d’outils ou de notes des testeurs. Le résumé narratif des résultats est rédigé par un chef de test ou le testeur, pour une phase de test à plus petite échelle. Comme d’habitude, ce rapport sera probablement moins formel et il y aura sans doute moins de données brutes pouvant servir de base à des analyses sophistiquées. Assurément, au cours des itérations, l’avancement en termes de fonctionnalités ou d’histoires livrées, testées et approuvées par les utilisateurs, pourrait être enregistré dans un outil ou sur un tableau KanBan public. De cette manière, les parties prenantes sont tenues informées de la progression tout au long de l’itération et il y a moins besoin d’un rapport formel à la fin de la période de test. La visibilité de l’avancement est une préoccupation clé pour les équipes agiles. Avec des réunions debout régulières, peut-être quotidiennes autour d’un tableau Scrum par exemple, les membres de l’équipe partagent leur compréhension du progrès, se questionnent mutuellement et se mettent d’accord sur la situation (et les prochaines étapes) en continu. Ainsi, un rapport de test formel peut ne jamais être nécessaire car l’équipe est toujours informée et à jour. Si les testeurs tiennent des notes écrites de leurs activités de session, il n’y a pas de données exploitables pour des rapports automatisés, donc le compte rendu des sessions et de la progression pourrait être présenté de façon publique et visuelle. Cela exige une grande discipline et de bonnes aptitudes à la communication de la part des testeurs. Le chef de test ou manager devra alors fournir un rapport informatif correspondant pour les parties prenantes, basé sur des retours oraux.

Quelques conseils

Le sujet de la documentation dans les projets est un point sensible aussi bien pour les testeurs que pour les autres membres de l’équipe projet.

La plupart des gens considèrent la rédaction de documentation comme une corvée.

Voici quelques éléments à garder à l’esprit lors de la conception de votre documentation.

La documentation doit avoir un objectif et un public bien définis. Si votre public n’a pas besoin de la documentation, il ne la lira pas. Si cela ne correspond pas à leurs propres buts, ils ne s’y investiront pas.
Il est généralement préférable de consigner l’activité avant ou au moment où vous la réalisez. Par exemple, la TDD capture les tests avant d’écrire le code. Les journaux de session de test doivent être enregistrés pendant la session et non rédigés après coup.
Les données essentielles à enregistrer pour un aspect du test peuvent être minimales. Par exemple, une note de test dans un carnet peut suffire au testeur mais ne sera pas facilement analysable. Peut-être qu’un simple journal texte avec quelques balises pourrait être aussi rapide à saisir mais également analysable par un outil personnalisé.
Les procédures de test ne sont peut-être pas nécessaires si les testeurs connaissent bien le système à tester. Un simple objectif ou mandat de test peut suffire. Des cas de test préparés peuvent être documentés au minimum dans un tableur.

Enfin

La nécessité est la mère de la documentation.

Si vous préparez une documentation complète pour vos parties prenantes et qu’elles ne la lisent pas, c’est qu’elles n’y voient pas de valeur.

Il vaut mieux proposer à une partie prenante une feuille blanche et ajouter ensemble les sujets dont elle a besoin dans un document, et travailler à partir de là. Il se peut qu’elle demande des pages et des pages de contenu, mais ce dont elle a réellement besoin est sans doute bien plus simple. Continuez de demander : « pourquoi veulent-ils cela ? »

Merci d’avoir lu cet article, rendez-vous la prochaine fois pour retrousser vos manches et attaquer un peu de planification de tests.

Inscrivez-vous à la newsletter The QA Lead pour être informé lorsque de nouvelles parties de la série sont publiées. Ces articles sont des extraits du cours Leadership In Test de Paul, que nous recommandons vivement pour approfondir ce sujet ainsi que d'autres thèmes. Si vous décidez d'y participer, utilisez notre code promo exclusif QALEADOFFER pour bénéficier de 60 $ de réduction sur le prix total du cours !

Want more from The CTO Club?