keep-the-caveat-with-the-number

Vous placez un chiffre mesuré quelque part où un lecteur le verra : un README, une landing page, des notes de version, un tableau de bord, un rapport. Le chiffre est vrai et il a besoin d'une phrase à côté pour ne pas induire en erreur — l'échantillon était petit, la tranche était facile, l'effet n'était pas significatif, le benchmark était le nôtre.

Cela ne s'applique pas à un chiffre dont le sens est complet en soi. « Le build a pris 41 secondes » n'a besoin de rien.

1. Écrivez la réserve d'abord, avant le chiffre. Si vous ne pouvez pas énoncer la limite en une phrase, c'est que vous ne comprenez pas encore assez bien la mesure pour la publier.
2. Rendez la réserve structurellement rattachée. Mettez-la dans le même composant, la même ligne de tableau, le même retour de fonction — quelque chose qui ne peut pas afficher le chiffre sans elle.
3. Placez-la au-dessus du chiffre, ou à côté. Pas en dessous.
4. Faites en sorte que le chiffre lui-même soit dérivé : lisez-le depuis l'artefact que la mesure a produit, pour qu'il bouge quand la mesure bouge.

Appliqué en excès, cela alourdit un reporting ordinaire : tous les chiffres ne sont pas des benchmarks, et une réserve sur un chiffre qui n'en a pas besoin habitue les gens à sauter les réserves.

Le risque le plus difficile à percevoir est qu'un mécanisme donne l'impression d'être toute la réponse. Un composant qui affiche toujours une réserve quelconque ne vérifie pas si c'est la bonne réserve. La phrase doit quand même être écrite honnêtement par une personne ; ceci empêche seulement qu'elle soit retirée par la suite.