Les développeurs écrivent souvent une mauvaise documentation, en supposant que les utilisateurs partagent leurs biais et leurs connaissances. Pour surmonter cela, l'auteur a payé de vrais utilisateurs 25 euros de l'heure pour tester leur README d'Activity Bot en suivant les instructions à voix haute tout en partageant leur écran. Cela a révélé des défauts critiques : liens de démonstration cassés, étapes de renommage de fichiers confus, termes techniques peu clairs, mauvais ordre des sections et objectif du logiciel non expliqué.
L'auteur a pris des notes manuscrites, a mis à jour le README après chaque session et a retesté avec de nouveaux utilisateurs. Au cours de plusieurs sessions, ils ont déboursé 150 euros pour des retours francs. Ce processus a mis en évidence que les vrais utilisateurs exposent des hypothèses cachées — comme le besoin de sudo, les exigences de redémarrage et les règles de citation — que les développeurs négligent.
Contrairement aux LLMs, les vraies personnes apportent de l'humour, des perspectives uniques et des indices émotionnels comme la frustration, qui signalent où la documentation échoue. L'auteur compare cela à son expérience de rédaction technique sur GOV. UK, où la relecture humaine a transformé un prose fleurie en des documents clairs et utilisables.
Bien que le README ne soit pas parfait, il est désormais demonstrablement plus facile à suivre. La leçon fondamentale : les développeurs doivent tester la documentation avec de vraies personnes qui pensent à voix haute, même non rémunérées, pour découvrir les angles morts et améliorer l'utilisabilité.
Source: Hacker News · Résumé par HeadlinesBriefing