I paid people to try and follow my README

Terence Eden describes a practical experiment to improve a README by paying people to follow it while thinking aloud. He recruited volunteers on Mastodon, paid €25 for roughly an hour each (about €150 total), and watched them share their screens over video calls. Testers were asked to narrate their actions, confusions, delights and frustrations while Eden took handwritten notes and iteratively updated the README between sessions. He emphasizes removing authorial bias by observing real users rather than relying on simulated testing.

The sessions revealed concrete, fixable problems: a broken demo link; users opening READMEs in a terminal; unclear instructions for renaming files (including hidden files); ambiguity about whether a demo should be web-hosted or local; inconsistent quoting; confusing jokes and unexplained jargon; poor section ordering; failure to state what the software does; a technically interesting section that confused everyone; and assumptions about web server permissions. Eden argues real humans are superior to LLM simulations for this work because they provide tone, immediate questions and visible frustration, which guided meaningful improvements. He doesn’t claim perfection but reports a demonstrably easier first-run experience and urges developers to run live tests with users, paid or volunteer.