Revue formelle
La revue formelle est un type de revue par les pairs où chaque relecteur examine le produit de travail seul, plusieurs jours avant une séance qui consolide les trouvailles. Le BABOK la range parmi les sept types de revue et lui donne dans sa définition même son autre nom, «Formal Walkthrough (also known as Team Review)»: une technique formelle qui sert aux revues par les pairs comme aux revues par les parties prenantes (§10.37.3.2). Wiegers, qui l'appelle team review, la résume d'un mot, une «inspection-lite», planifiée et structurée, moins formelle et moins rigoureuse qu'une inspection. Elle partage son nom, sa séance et son compte avec la revue informelle: le tableau des objectifs de Wiegers en accorde sept à chacune, et ce ne sont pas les mêmes sept. Une seule activité les sépare, la lecture individuelle avant la séance, et elle échange trois objectifs contre trois autres. La revue formelle trouve ce qui est faux sur la page; la revue informelle trouve ce qui n'a pas de page.
Objectif
Des sept revues du BABOK, la revue formelle est celle dont la définition tient en deux activités: elle emploie la lecture individuelle et la consolidation en équipe que l'on rencontre souvent dans l'inspection, et les walkthroughs, ajoute le BABOK dans la même phrase, servent aux revues par les pairs comme aux revues par les parties prenantes (§10.37.3.2). Chaque relecteur reçoit le produit de travail plusieurs jours avant la séance et l'examine de son côté; la séance rassemble ce que chacun a trouvé seul. Toute l'économie de la technique sort de ces deux seules activités.
Le BABOK donne à cette revue son autre nom dans la définition elle-même, «Formal Walkthrough (also known as Team Review)», et c'est ce second nom qu'il faut avoir en tête pour lire Wiegers. Son tableau comparatif porte deux colonnes, team review et walkthrough, qui sont la revue formelle et la revue informelle (10.37d) du BABOK.
Le BABOK énumère sept objectifs possibles pour une revue (§10.37.3.1), et la revue formelle en sert quatre, dont un à moitié. Éliminer des défauts: le tableau 3-3 de Wiegers marque cette ligne pour les six méthodes qu'il compare, et il la borne pour celle-ci, une étude industrielle ayant trouvé que ce type de revue en équipe découvrait seulement deux tiers autant de défauts par heure que les inspections (Van Veenendaal 1999). Vérifier la conformité à une spécification ou à une norme: l'objectif du BABOK en réunit deux, et Wiegers les sépare. Il accorde à la team review la conformité à une spécification et lui refuse la conformité à une norme, et sa prose dit la même chose, la revue sert à identifier ce par quoi le produit ne satisfait pas ses spécifications. La moitié qui sort trouve où aller: une norme unique qu'il faut trancher relève de la revue technique (10.37c), et un lecteur seul avec le texte de la norme d'un desk check (10.37e) ou d'une revue en circulation (10.37f). Établir un consensus sur une approche ou une solution: étant moins formelle que l'inspection, écrit Wiegers, la revue en équipe peut consacrer une partie de la séance à discuter des idées de solution et à faire converger les participants sur une approche technique. L'accord y laisse de surcroît une trace, puisqu'une appréciation du produit sort de la séance (Wiegers, tableau 3-2). Instruire les relecteurs sur le produit: Wiegers y voit une bonne occasion d'apprentissage pour les participants, et la revue informelle (10.37d) sert cet objectif aussi bien.
Trois des sept lui échappent. S'assurer que le produit est complet et exact: le tableau 3-3 ne marque la complétude que pour deux méthodes, l'inspection (10.37a) et la revue informelle (10.37d). La revue formelle porte pourtant sur le produit de travail entier; ce qui lui manque est l'objectif d'établir que rien n'y manque. Répondre à une question, trancher un point, explorer des options: le cinquième objectif du BABOK en réunit trois, et la revue formelle n'en prend aucun. Wiegers accorde l'exploration d'options à la revue informelle et à la programmation en binôme. Une question bornée se pose à un pair disponible, ce qui est le terrain de la revue ad hoc (10.37g); un point qui doit être tranché se convoque en revue technique (10.37c); des options se pèsent l'une contre l'autre devant le groupe que l'auteur a réuni, ce qui est celui de la revue informelle (10.37d). Mesurer la qualité du produit: le tableau 3-3 réserve à l'inspection (10.37a) la mesure de la qualité d'un document.
Deux lignes du tableau de Wiegers que la liste du BABOK ne porte pas sont pourtant celles de cette revue. Évaluer la lisibilité et la maintenabilité du document: la lecture individuelle est la rencontre privée du relecteur avec le document, et c'est là que se juge s'il se lit sans son auteur. Le tableau 3-3 marque cette ligne pour l'inspection, la team review, la programmation en binôme et la revue en circulation (10.37f), où les lecteurs rencontrent le document chacun de son côté. Dans une revue formelle, l'auteur est dans la salle pendant la séance, et le relecteur a rencontré le document sans lui pendant la lecture. Collecter des données pour améliorer le processus: le tableau 3-3 ne marque cette ligne que pour deux méthodes, l'inspection et la team review. Wiegers écrit que l'équipe collecte des données sur l'effort de revue et sur les défauts trouvés, et son tableau 3-2 borne la pratique, la collecte et l'analyse de données y valant «peut-être» pour la team review, là où elles valent «oui» pour l'inspection. L'objectif est le sien; l'activité reste facultative.
Ce qu'elle laisse derrière elle, c'est un jeu consolidé de trouvailles et une appréciation du produit. Le premier est ce que nomme la définition du BABOK, la lecture individuelle puis la consolidation en équipe, et le scribe le consigne en séance (tableau 10.37.1). La seconde est chez Wiegers: son tableau 3-2 marque pour la team review la ligne appréciation du produit prononcée, et sa prose dit ce que cela veut dire, une revue en équipe permet à un groupe de gens qualifiés de juger si le produit est apte à l'usage. La séance prononce, et elle ne revient pas: le tableau 3-1 marque pour la team review la correction et lui refuse la vérification. L'auteur corrige. Une trouvaille qui doit survivre à la séance relève du suivi des items (10.26).
Usage
Quand l'utiliser
- Un accord sur le produit doit pouvoir être attesté: l'appréciation sort de la séance (Wiegers, tableau 3-2).
- Le produit doit être confronté à une spécification: Wiegers accorde cette conformité à la team review (tableau 3-3).
- Il faut savoir si le document se lit sans son auteur: chaque relecteur le rencontre seul, avant la séance.
- Des lectures individuelles doivent être consolidées en équipe: c'est la définition même du BABOK (§10.37.3.2).
- La revue doit alimenter des données sur le processus de revue: le tableau 3-3 ne marque cet objectif que pour l'inspection et la team review.
- Le produit ne demande pas toute la rigueur d'une inspection: Wiegers place là le cas propre de la technique, un groupe ou un produit de travail qui n'exige pas le processus d'inspection complet.
Quand ne pas l'utiliser
- Le produit n'est pas critique au point de payer une séance préparée: le BABOK écrit que les revues en équipe rigoureuses demandent du temps et de l'effort, et que seuls les produits de travail les plus critiques pourraient donc être revus par une inspection ou un walkthrough formel (§10.37.4.2). Un desk check (10.37e) met un relecteur compétent devant le document; une revue en circulation (10.37f) en met plusieurs, chacun de son côté.
- Ce qui manque compte plus que ce qui est faux: le tableau 3-3 refuse la complétude à la team review. Une inspection (10.37a) couvre le produit par petits morceaux; une revue informelle (10.37d) le fait dérouler de bout en bout par son auteur.
- La question porte sur une norme unique, et il faut la trancher: Wiegers donne à la team review la conformité à une spécification et lui refuse la conformité à une norme (tableau 3-3). Une revue technique (10.37c) existe pour cette matière et pour elle seule.
Description
Lire seul, puis consolider
Le BABOK ne donne aucune étape à cette technique. Sa définition en nomme deux activités, et Wiegers les décrit l'une et l'autre.
La lecture individuelle. Les participants reçoivent le matériel de revue plusieurs jours avant la séance et il est attendu d'eux qu'ils l'étudient chacun de son côté. C'est le coût principal de la technique et c'est sa condition: une revue formelle où personne n'a lu se met à lire, et une lecture en salle est une autre revue.
La consolidation en séance. Wiegers décrit le mécanisme en une phrase, et il le construit par contraste avec l'inspection: au lieu de faire décrire par un participant un petit morceau du produit à la fois, le modérateur demande aux participants s'ils ont quelque chose sur une section ou une page donnée. Son tableau 3-2 le confirme deux fois, la granularité du matériel présenté est la page ou la section, et celui qui présente le matériel est le modérateur. Le BABOK dit la même chose du côté du rôle: l'animateur veille à ce que chaque section pertinente du produit de travail soit couverte (tableau 10.37.1). La revue formelle passe le produit en revue section par section, et demande à chacun ce qu'il a trouvé.
Qui anime, qui consigne. Le BABOK range l'animateur parmi les rôles applicables à l'inspection et au walkthrough formel, et il précise que cet animateur ne devrait pas être l'auteur, pour ne pas compromettre la revue (tableau 10.37.1). Il range le scribe pour les mêmes revues et pour la revue informelle (10.37d): c'est l'animateur qui sépare les deux walkthroughs, et le scribe leur est commun.
Où se situe la revue formelle
Le BABOK liste ses sept types de revue par formalité décroissante et qualifie les trois premiers de techniques formelles, les quatre suivants de techniques informelles (§10.37.3.2). Deux questions binaires traversent ce classement: la séance est-elle planifiée, le relecteur examine-t-il le produit seul avant de parler? La revue formelle répond oui aux deux, comme l'inspection (10.37a) et la revue technique (10.37c).
Chez les deux normes du domaine, le mot walkthrough désigne la revue que l'auteur conduit lui-même, la moins formelle de leurs types: l'IEEE 1028-2008 la range parmi ses cinq types de revue, l'ISO/IEC 20246:2017 parmi ses dix, et c'est celle que le BABOK appelle revue informelle (10.37d). La revue formelle, elle, se lit chez Wiegers, qui l'appelle team review, et le BABOK reprend ce nom dans sa définition.
Les deux walkthroughs portent sept objectifs chacun
Le tableau des objectifs de Wiegers compare six méthodes de revue sur quatorze objectifs. Sa colonne team review en porte sept, sa colonne walkthrough, qui est la revue informelle (10.37d), en porte sept, et seule l'inspection (10.37a) en porte davantage, huit. Quatre lignes leur sont communes. Les six autres se répartissent trois et trois. C'est là que se joue la différence entre les deux revues qui partagent un nom.
| Objectif (Wiegers, tableau 3-3) | Revue formelle (10.37b) | Revue informelle (10.37d) |
|---|---|---|
| Éliminer des défauts | Oui | Oui |
| Instruire les relecteurs sur le produit | Oui | Oui |
| Établir un consensus sur une approche | Oui | Oui |
| Contrôler que des changements ont été faits correctement | Oui | Oui |
| Vérifier la conformité à une spécification | Oui | Non |
| Évaluer la lisibilité et la maintenabilité du document | Oui | Non |
| Collecter des données pour améliorer le processus | Oui | Non |
| S'assurer que le produit est complet et exact | Non | Oui |
| Explorer des approches alternatives | Non | Oui |
| Dérouler un cas concret à travers le produit | Non | Oui |
Une seule activité sépare les deux colonnes, et le tableau 3-1 de Wiegers la nomme: la préparation, qu'il marque pour la team review et qu'il refuse à la revue informelle (10.37d). Le BABOK dit la même chose, les relecteurs de celle-ci pouvant se contenter d'une préparation minimale. Cette activité échange trois objectifs contre trois autres.
Ce qu'elle achète, seul un lecteur seul avec le document peut le produire: la confrontation du produit à une spécification, un jugement sur la lisibilité du document lu sans son auteur et des données que quelqu'un a comptées. Ce qu'elle coûte, seule la narration de l'auteur en séance peut le produire: la complétude du produit de bout en bout et les options que l'on pose l'une contre l'autre.
La complétude est la ligne contre-intuitive. L'animateur du BABOK veille à ce que chaque section pertinente du produit de travail soit couverte (tableau 10.37.1). Le modérateur de Wiegers demande aux participants s'ils ont quelque chose sur une section ou une page donnée. Les deux textes décrivent la même activité, et le rapprochement des deux lignes est le nôtre: la revue formelle parcourt les sections du produit, et ce qui n'a de section nulle part n'est demandé à personne. L'inspection (10.37a) couvre le produit par petits morceaux; la revue informelle (10.37d) le fait dérouler de bout en bout par son auteur, et le cas qui n'a d'étape nulle part s'y signale. La revue formelle trouve ce qui est faux sur la page. La revue informelle trouve ce qui n'a pas de page.
Les pièges
La séance se met à lire. Quatre relecteurs entrent dans la salle, deux ont lu, deux ouvrent le document. La séance devient une lecture collective, la consolidation n'a rien à consolider, et l'heure passe à découvrir ce que la préparation devait apporter. Valider que les relecteurs ont examiné le produit avant le début de la séance est ce que le tableau 10.37.1 confie à l'animateur, et c'est la seule tâche de la technique qui se fasse avant que la salle ne se remplisse.
Le cas où personne n'a lu le document est le cas standard. Une pratique de terrain y répond par la conception plutôt que par le contrôle: la lecture se tient dans la salle, délibérément. L'invitation part avec le document, demande qu'il soit annoté, annonce que la lecture sera collective, nomme les parties prenantes dont la présence est impérative et admet un remplaçant qui peut engager son service. En séance, l'animateur lit le document section par section et le paraphrase, ce qui est le rôle de lecteur que Wiegers documente dans l'inspection, et le groupe converge sur une seule interprétation. Les questions, les vetos et la négociation entre parties prenantes se traitent immédiatement, dans la salle, et ce qui doit être adapté, complété, clarifié ou supprimé s'écrit dans le document pendant la séance. Ce que les personnes présentes ne peuvent pas trancher part dans une section «points ouverts», avec un mini-RACI: qui s'en occupe, qui est consulté, qui valide, une ou deux personnes nommées au plus. Sans point ouvert, le document est accepté; avec des points ouverts, il est accepté sous réserve, et lorsque chacun d'eux a été traité il change de version, passe en accepté et se distribue selon le RACI du projet. Si une partie prenante clé ne vient pas et ne délègue personne, la séance est annulée.
La séance dérive vers les solutions. Wiegers avertit que l'équipe peut se laisser entraîner sur des discussions tangentes, et il admet dans la même page qu'une revue en équipe peut consacrer du temps de séance à discuter des idées de solution. Les deux phrases tiennent ensemble, et l'animateur les tient: la matière de la séance est ce que chacun a trouvé, section par section, et un débat de conception qui s'ouvre sur une trouvaille se note et se reprend ailleurs.
Faire animer la séance par l'auteur. Le BABOK précise que l'animateur ne devrait pas être l'auteur, afin de ne pas compromettre la revue (tableau 10.37.1). L'auteur qui anime décide de l'ordre des sections, du temps passé sur chacune et du moment où l'on passe à la suivante, et c'est exactement ce que la technique lui retire pour donner à ses trouvailles la valeur qu'elles ont.
La prendre pour une inspection. Elle est formelle, elle est préparée, elle tient séance et elle prononce une appréciation, et il est facile d'en conclure que la boucle est fermée. Le tableau 3-1 de Wiegers marque pour la team review la correction et lui refuse la vérification. L'auteur corrige, et une trouvaille qui doit survivre à la séance entre au suivi des items (10.26) le jour même. Une revue qui referme elle-même la boucle qu'elle a ouverte est une inspection (10.37a).
Considérations IA
Le bien propre de cette revue est la lecture individuelle: chaque relecteur rencontre le produit seul, avant que la salle ne se remplisse. C'est là qu'un grand modèle de langage sert le mieux, et c'est aussi la seule activité de la technique dont il ne peut pas répondre.
Préparer sa propre lecture. Le relecteur doit arriver en séance en ayant lu le paquet seul. Un modèle peut passer le paquet contre la spécification avant lui: l'exigence sans critère d'acceptation, le terme employé dans deux sens, la section que la spécification demande et que le paquet ne porte pas. La lecture du relecteur se dépense alors sur ce que seul un lecteur du métier peut voir.
Préparer la consolidation. La séance d'une revue formelle est une consolidation, et Wiegers avertit qu'elle peut s'égarer. Un modèle peut fusionner à l'avance les trouvailles des quatre relecteurs par section et faire remonter les deux endroits qui comptent: là où deux relecteurs ont trouvé la même chose, et là où ils se contredisent. C'est le travail que la salle fait à la main, et le faire avant rend la séance à ce qu'elle a de propre, la décision de ce qui reste une trouvaille.
Il ne peut pas être la lecture individuelle. L'animateur a pour tâche de valider que les relecteurs ont examiné le produit de travail avant le début de la séance (tableau 10.37.1), et le passage d'un modèle n'est la lecture de personne. Une séance qui consolide les trouvailles d'une machine a consolidé ce dont personne ne répond. L'appréciation, du reste, est le jugement d'un groupe de gens qualifiés (Wiegers, tableau 3-2), et un modèle ne la signe pas.
La protection des données. Un paquet d'exigences de cyberadministration contient des données personnelles, numéro AVS compris. La nLPD passe avant la productivité, et la règle de l'organisation, quel modèle, quelles données, hébergé où, se fixe avant que le paquet ne parte aux relecteurs.
Exemples
Une revue formelle produit un jeu consolidé de trouvailles que chacun a faites seul et une appréciation prononcée sur le produit.
| Section du paquet | Trouvé seul par | Ce que la séance en a fait | Nature |
|---|---|---|---|
| §2.4 Identification du requérant | Relecteur A (métier) et relecteur C (sécurité) | Les deux avaient relevé le même écart: la spécification exige une authentification de niveau substantiel, le paquet n'en demande aucune. Consolidé en une seule trouvaille. | Défaut |
| §3.1 Données transmises à la commune de départ | Relecteur B (données) | Le paquet transmet le numéro AVS à la commune de départ; la spécification ne l'autorise que vers la commune d'arrivée. | Défaut |
| §3.2 Format de l'annonce | Relecteur B (données) | «Le paquet cite la norme eCH-0011 sans dire quelle version fait foi.» La séance n'a pas tranché: la question de la norme part en revue technique (10.37c). | Question ouverte |
| §5 Délais | Relecteur D (juridique) | Le paquet compte les 14 jours depuis la date du bail; le règlement cantonal les compte depuis l'emménagement effectif. | Défaut |
| §6 Émoluments | Relecteur A (métier) | Le paquet fige l'émolument à CHF 20 par annonce. C'est un paramètre communal: trois communes du canton le fixent à CHF 0, une à CHF 40. | Suggestion |
| §7 Annonces en cours à la mise en service | Relecteur C (sécurité) | Deux relecteurs avaient lu la même phrase autrement. La salle s'est accordée: le portail ne traite que les annonces ouvertes après la mise en service. | Point accordé en séance |
| Appréciation | Le paquet n'est pas apte à l'usage en l'état. |
|---|---|
| Ce qui bloque la remise | Les trois écarts à la spécification (§2.4, §3.1, §5) sont à corriger avant la remise. |
| Ce qui ne bloque pas la remise | La question de la norme eCH-0011 (§3.2) part en revue technique (10.37c). |
Les six trouvailles ont été faites seules, avant la séance, et la séance les a consolidées: là où deux relecteurs avaient vu le même écart, il ne reste qu'une ligne.
Aucune ligne ne signale une section absente. L'animateur a parcouru les sections du paquet, et ce qui n'a de section nulle part n'est demandé à personne. Ce que le paquet ne dit pas se cherche dans une inspection (10.37a) ou dans une revue informelle (10.37d), où l'auteur déroule le produit de bout en bout.
La séance a prononcé une appréciation sur le paquet. L'auteur corrige, et ce qu'il advient des corrections ne relève plus de la technique (Wiegers, tableau 3-1: correction, oui; vérification, non); les deux points qui doivent survivre à la séance (§3.2 et §6) entrent au suivi des items (10.26).
Coût
| Phase | Niveau | Justification |
|---|---|---|
| Préparation | Élevé | Wiegers marque pour la team review la planification et la préparation (tableau 3-1). C'est la seule phase qui sépare cette revue de la revue informelle (10.37d): chaque relecteur reçoit le produit plusieurs jours avant la séance et l'examine seul. Le coût est celui d'une lecture complète, multiplié par le nombre de relecteurs, et il est payé avant que la salle ne se remplisse. |
| Exécution | Moyen-Élevé | Une séance, plusieurs personnes dans la même salle au même moment. L'animateur parcourt le produit section par section (tableau 3-2, granularité: la page ou la section) et consolide ce que chacun a trouvé de son côté. |
| Documentation | Moyen | Le scribe consigne en séance (tableau 10.37.1). Il en sort un jeu consolidé de trouvailles et une appréciation du produit (Wiegers, tableau 3-2). Les données sur l'effort et sur les défauts sont un «peut-être» dans ce même tableau: elles se collectent si quelqu'un les a demandées, et le temps se paie. |
Outils
La revue formelle demande d'abord un moyen de mettre le produit de travail entre les mains des relecteurs plusieurs jours avant la séance et un endroit où chacun consigne ce qu'il trouve pendant sa lecture. Un fil de commentaires dans l'outil où le produit a été fabriqué suffit, à une condition: que les trouvailles portent la section à laquelle elles se rattachent, parce que c'est par section que la séance les rappellera.
Elle demande ensuite une liste de contrôle de défauts. Wiegers marque cette ligne pour la team review dans son tableau 3-2, là où il la refuse à la revue informelle (10.37d), et la liste se fabrique à partir de ce contre quoi le produit doit tenir: la spécification, article par article. C'est elle qui donne à la lecture individuelle sa forme, et c'est ce qui distingue quatre lectures d'une revue.
Elle demande enfin de quoi consolider en séance et de quoi écrire. Le scribe consigne (tableau 10.37.1). Deux artefacts sortent de la salle, le jeu consolidé de trouvailles et l'appréciation du produit (Wiegers, tableau 3-2). Ce qui doit vivre au-delà de la séance vit ailleurs: une trouvaille qui reste ouverte relève du suivi des items (10.26), et une question de norme laissée en suspens relève d'une revue technique (10.37c).
Sources
- IIBA, A Guide to the Business Analysis Body of Knowledge (BABOK Guide) v3, §10.37 Reviews (§10.37.3.1, les sept objectifs; §10.37.3.2, les sept types et la définition du walkthrough formel; tableau 10.37.1, les rôles; §10.37.4.2, les limitations).
- Karl E. Wiegers, Peer Reviews in Software: A Practical Guide, Addison-Wesley, 2002, chapitre 3, «Peer Review Formality Spectrum» (tableau 3-1, activités par type de revue; tableau 3-2, caractéristiques comparées; tableau 3-3, objectifs et méthodes; la section consacrée à la team review).
- ISO/IEC, ISO/IEC 20246:2017, Software and systems engineering: Work product reviews.
- IEEE, IEEE Std 1028-2008, IEEE Standard for Software Reviews and Audits.
- Olivier Wagner, «Revue de document, je lis à voix haute en séance», SmartGecko Academy, 2024 (la lecture collective en séance, son déroulé et son économie).