chimera-give-the-denominator

Vous vous apprêtez à mettre un taux, un pourcentage ou un décompte dans un rapport, un message de commit, un tableau de benchmark, ou un message à quelqu'un qui va agir dessus. « 34 % des exécutions ont échoué. » « Erreurs multipliées par 3. » « La couverture a baissé. »

Cela ne s'applique pas à un chiffre que le lecteur peut déjà décomposer : une latence unique mesurée, un numéro de version, un nombre de fichiers dans un diff qu'il a sous les yeux. Le risque est spécifique à un agrégat — une quantité calculée en divisant un ensemble que vous avez choisi par un autre ensemble que vous avez choisi, où les deux choix sont invisibles dans la phrase.

1. Écrivez toujours les décomptes bruts à côté du taux : 34% (17/50 runs). Si vous ne pouvez pas énoncer le dénominateur, vous ne savez pas encore ce que vous avez mesuré.
2. Dites de quel dénominateur il s'agit. Les exécutions tentées et les exécutions terminées sont des ensembles différents, et diviser par les terminées supprime silencieusement les plantages — précisément la population qui vous a fait regarder.
3. Ventilez le numérateur par cause avant de le publier. Sur ces 17 échecs, combien relèvent d'un ticket déjà ouvert, d'un timeout instable connu chez le fournisseur, d'une fixture qui échoue sur cette machine ? Rapportez la ventilation : 17 failed — 14 are the known connect timeout, 3 unexplained.
4. Lancez la même mesure sur une référence inchangée et soustrayez. Le chiffre qui compte est la part qui ne survit pas sur main.
5. Quand n est assez petit pour qu'un échantillon de plus déplace le chiffre affiché de plusieurs points, mettez cette phrase-là dans le rapport à la place du pourcentage.

Appliqué à tout, cela transforme une prose lisible en marécage de parenthèses, et les lecteurs se mettent à sauter les parenthèses — ce qui est pire que le problème d'origine, car les dénominateurs sont désormais sur la page et personne ne les lit. Réservez la décomposition complète aux chiffres sur lesquels quelqu'un va agir.

Le risque le plus aigu va dans l'autre sens : la ventilation par cause est aussi l'outil qui fait paraître petit un vrai problème. Étiqueter quatorze échecs comme « bruit connu » n'est honnête que si l'étiquette a été attribuée avant que vous ne voyiez dans quel sens elle arrangeait les choses. Si vous vous surprenez à élargir la catégorie « connu » pendant la rédaction du résumé, le chiffre était la conclusion, pas la preuve.

Un dénominateur énoncé ne rachète pas non plus un mauvais dénominateur. 2/3 (n=3), ce sont toujours trois exécutions ; le dénominateur rend la faiblesse visible, il ne la corrige pas.