Terence Eden offered people €25 for an hour spent trying to install ActivityBot using its README. They shared their screens and spoke their thoughts aloud; he took notes, fixed the instructions, and tested again with the next person. Around €150 bought a view of the installation experience that knowing his own software had hidden from him.

The failures weren’t just broken commands:

  • The demo link was wrong, and the guide hadn’t explained what the software did.
  • Renaming hidden files, quoting text, and technical terminology needed more explanation.
  • Section ordering, jokes, and a technically interesting digression made the instructions harder to follow.

The useful lesson is to test documentation as an experience, not merely proofread it as text. Watching someone hesitate tells you where your explanation stops working—even when every sentence seems obvious to you.

The 123-comment thread on Hacker News adds a concrete missing prerequisite, a testing-method caveat, and a counterexample to dismissing automated readers entirely.

What the thread adds

  • WhyNotHugo — identifies a setup dependency they say the README still omits: “There’s a zeroth step missing from both the Quickstart and Full Set Up: install php-fpm, configure it, and configure your http server to serve using it as a backend.” PHP-FPM runs PHP application code behind the web server; this is a commenter’s inspection, not a finding reported in the essay.
  • nkrisc — distinguishes iterative repair from a more controlled usability study: “Normally though you don’t modify it after each participant.” They allow that this niche case “might be fine, if less rigorous.”
  • tilemarch — reports using AI agents to try API instructions, but describes the limit: “an agent doesn’t tell you the doc is confusing, it just does something wrong with full confidence.” Their experience is a counterpoint to treating automated tests as useless, not evidence that they replace people.

HN handles are pseudonymous. HN publishes no per-comment scores; its ordering is HN’s own ranking. These excerpts are a slice of the thread, not a consensus.