I paid people to try and follow my README
Points and comments are a snapshot, not live.
Paying real users to find flaws in a README reveals hidden assumptions and improves documentation.
Terence Eden paid six people €25 each for an hour to test his ActivityBot project's README. Participants shared their screens and spoke aloud while installing the software. The process uncovered a broken demo link, confusing terminology, unclear renaming steps for hidden files, misunderstood jokes, and a technically interesting but irrelevant section. After each session, Eden updated the README and retested with the next participant. He prefers real-user testing over LLM simulation because human testers reveal frustration, offer unique perspectives, and can make the developer laugh. Total cost was about €150.
What commenters are saying
Commenters broadly endorse the approach, identifying it as standard UX usability testing with compensated participants. Several criticize overuse of emojis in READMEs, calling them distracting and reminiscent of LLM-generated content. A top comment notes a missing prerequisite (PHP-FPM configuration), sparking discussion on how far back in the stack documentation should go. One commenter recommends the diataxis.fr framework for organizing documentation by purpose. Another suggests treating READMEs as executable code, with a complete list of commands tested from a clean machine.