I paid people to try and follow my README

Original Article ↗ Hacker News Discussion ↗

Paying people to follow a project’s README like a script exposes just how many assumptions, omissions, and distractions creep into developer documentation. Commenters argue that READMEs should clearly state what the software does, list prerequisites, and provide a minimal, end-to-end setup path, with many criticizing emoji clutter, in-jokes, and AI-generated “slop” that obscure essential information. Several point out this kind of real-user testing mirrors UX usability practices and complements automated checks or LLM-based reviews, which still can’t judge clarity, boredom, or confusion the way humans do.

Overall reaction to “paying people to follow my README”

  • Many see this as standard usability testing applied to technical docs.
  • Several praise the idea and say similar internal practices (onboarding new hires via README, friction logs) catch many issues quickly.
  • A few argue you can often catch most problems yourself by strictly following your own instructions on a clean machine.

Level of detail and prerequisites

  • Strong sentiment that READMEs often omit critical “zeroth steps” (e.g., installing php-fpm, runtimes, or tools).
  • Consensus that a clear “Prerequisites” section is key, even if you don’t explain how to install each dependency.
  • Debate on how far back to go: some want commands from git clone onward; others note you can’t enumerate every OS/package manager.

Style: concision, structure, and what the software does

  • Frequent complaint: READMEs that never clearly state what the project does, only how to install it or list buzzwords.
  • Many prefer short, task-oriented READMEs that act as an entrypoint to richer docs rather than long “novels” or FAQs.
  • Frameworks like Diataxis and the tutorial vs. reference split are seen as useful for structuring docs.

Tone: emojis, jokes, and personality

  • Overuse of emojis is widely disliked; many associate emoji-heavy READMEs with LLM-generated content or childishness.
  • Light humor is acceptable to some if it doesn’t obscure meaning; others argue jokes and culture-specific references are confusing and not worth the risk.
  • Multiple people note that what’s funny to the author often doesn’t land for readers.

Humans vs. AI/agents in doc testing

  • Several suggest LLMs and agents are good at:
    • Following instructions step-by-step in sandboxes.
    • Highlighting missing steps and inconsistencies.
  • But humans are seen as essential for:
    • Judging boredom, clarity, and overall UX.
    • Exposing assumptions, confusing language, and cultural/knowledge gaps.

Installation friction and automation

  • Many lament projects that don’t “just run,” even with READMEs.
  • Containerization (Docker) and environment tooling (Nix, direnv) are praised for reproducible, low-friction setups.
  • Some argue truly polished software should automate setup instead of relying heavily on manual READMEs.