He paid strangers to follow his README. The demo link was broken

Terence Eden paid readers €25 each to open his README and narrate their confusion over a video call. Total cost: around €150. One of the early findings was that the link to his demo tool was wrong, in a README written by the same person who built the demo.

This was a follow-up to a post from October 2025 where he argued developers should spin up a fresh virtual machine and follow their own install docs line by line. The flaw in that method is biographical. You wrote the doc, so you auto-correct while reading: you know the flag needs two dashes, you know the service needs a restart. Paying strangers removes the auto-correct, because they have no idea what you meant.

The format comes straight out of a UX textbook. Recruit through Mastodon, share a screen, think out loud, watch where people hesitate. Confusion showed up in predictable places once someone else was watching. Renaming a file, especially a hidden one, stalled people. Section ordering stalled people. The jokes stalled people. A section he found technically interesting confused everyone. The README never stated what the software does in the first place. After each session he fixed what broke and re-tested with the next reader, one participant at a time, which a commenter correctly identified as standard usability testing, the kind Nielsen Norman Group has documented for years. Eden did technical writing on GOV.UK, where a second human stripped the flowery prose before publication; this is the same instinct, outsourced to whoever answers a Mastodon call.

The Hacker News thread, 391 points at the time of writing, pulled the discussion somewhere more current: what a README signals when some of its readers are generated. Multiple commenters said an emoji-studded README now reads as LLM output to them, a slop tell before a single command runs. Eden's answer came from his own session data: about half the participants liked the emojis, one objected, the rest had no strong preference. He kept them because they make him smile. Both things are true. The signal readers extract from formatting is real, and it no longer measures the effort it used to.

The more interesting split is functional. READMEs are now read by two species: humans installing things, and agents deciding how to work with a repository. One commenter argued that much of the noise comes from writing for both audiences in a single file, and pointed at arXiv research on AGENTS.md context files, updated in September. The paper found these files do not generally improve task success rates while adding over 20% to inference cost on average. Instructions get followed. Repository overviews, popular and recommended by model providers, added nothing measurable.

Whether agents can replace the paid humans got its own subthread, and the honest answer was: only for part of the job. One developer described agent reviewers catching real bugs, like pinch-zoom breaking while a finger rests on a joystick, and none of them flagging that the game was boring. He noticed that himself, on his phone, walking his character up to a house where nothing happened. Agents audit whether instructions can be followed. They do not notice dull. For an install README that might be enough. For everything else a README does, the boring detector still runs on wetware.

There is also a budget line worth stealing. Eden's NLnet grant for ActivityBot, applied for at €10,000, itemizes processing user feedback as its own funded phase. Most open source projects budget zero for finding out whether their instructions work, then pay for it later in support threads. The two-audience problem will not go away, either. Codecora covered the same split earlier this month from the memory side, asking where agent recall should end and documentation begin. The install guide is the other half of that question, and the cheapest instrument for it remains a screen share, a voucher, and one honest stranger.