Une notice utile décrit ce qui a répondu, à quelle date, sous quelles conditions. Elle ne décrit pas ce que le projet espérait.
L'intention aide à démarrer. La mesure sert à décider la suite.
Ce que dit une bonne pratique de documentation
La documentation technique vise à laisser un lecteur refaire le même geste et obtenir le même résultat, pas à raconter le plan.
Source : Write the Docs — Documentation Guide
Sur GitHub, le README d'un dépôt sert d'entrée : ce que fait le projet, comment commencer, ce qu'il faut savoir pour s'en servir.
Source : About the repository README file
Ce qui change quand on écrit la mesure
- On date le constat : jour, outil, version si elle est connue.
- On sépare « prévu » et « observé » : deux phrases, pas une seule.
- On garde la preuve courte : code de réponse, fichier vu, compteur lu.
La règle qui en sort
Avant de corriger, on écrit ce qui a été mesuré. Après la correction, on mesure à nouveau et on met à jour la notice. L'intention reste dans le fil de discussion ; le mode d'emploi porte le résultat.
À retenir
La notice retient le comportement constaté le jour du test. L'intention du projet ne remplace pas une mesure datée.