{
  "id": 13710102,
  "title": "I paid people to try and follow my README",
  "url": "https://urgent.news/2026/10/11/i-paid-people-to-try-and-follow-my-readme",
  "topic": "tech",
  "section": "Tech",
  "published": "2026-10-11T11:47:29.000Z",
  "source": {
    "name": "Hacker News",
    "slug": "hacker-news",
    "url": "https://shkspr.mobi/blog/2026/10/i-paid-people-to-try-and-follow-my-readme/"
  },
  "original_language": "en",
  "account": "Developers often struggle with creating comprehensive documentation. Many of us resort to RTFM, but the reality is that the \"FM\" part is frequently lacking. Our documentation typically consists of a haphazard collection of notes, outdated advice, and a forum filled with repetitive inquiries. This approach is not conducive to providing a positive user experience. It's a belief of mine that there exists a superior method. As previously mentioned, it is essential to rigorously test your README. Set up a new virtual machine, go through the documentation, and assess its clarity. However, it is incredibly challenging to remain oblivious to one's own preconceptions. To overcome these biases, I resorted to a unique solution. As part of my NLnet grant application for ActivityBot, I aimed to assess the installation experience from the perspective of real users. I was willing to pay them €25 for an hour of their time. I reached out on Mastodon, assembled a small group of volunteers, and conducted video calls with them. The process was straightforward. I explained that I sought feedback on the initial user experience. I was well aware that it was not flawless and was eager for constructive criticism. I asked each volunteer to share their screen and, most importantly, to verbally articulate their actions. Describe what they were doing, what aspects they struggled with, what confused them, what intrigued them, and what frustrated them. I took detailed handwritten notes and devoted several hours to listening to their critiques. After each session, I revised the README based on their feedback, then proceeded to test it again with the next participant. In total, I allocated approximately €150 to facilitate several individuals in providing critical feedback. While some may argue that I could have employed an LLM to simulate a diverse range of users, I firmly believe in the value of engaging with real individuals. People possess a unique ability to entertain, reveal their surroundings, and provide a distinct viewpoint on the issue. Furthermore, they are genuinely delighted when rewarded with a €25 voucher. Some volunteers are even grateful for the experience, regardless of whether they receive compensation. During my tenure at GOV.UK, where I specialized in technical writing, my eloquent prose was subjected to a second review by another human. They dismantled my ornate phrases, transforming the document into a more straightforward and accessible format. These individuals were instrumental in identifying errors that a spell checker would have missed. They were capable of engaging in meaningful conversations with me. Most importantly, they could perceive the frustration in their voices, which served as a clear indicator that a mistake needed correction. I cannot guarantee that ActivityBot's README is now perfect, but it is demonstrably more user-friendly. Developers must communicate with real people. It is not always necessary to compensate them, but finding a few individuals willing to verbalize their thoughts while attempting to follow your instructions can significantly enhance the quality of your documentation.",
  "summary": null,
  "key_points": [
    "Paid volunteers €25 to test README",
    "Engaged real users to provide feedback",
    "Revised README based on user critiques"
  ],
  "editors_take": null,
  "illustration": null,
  "coverage": {
    "outlets": 1,
    "also_reported_by": []
  },
  "ai_generated": true,
  "disclaimer": "Summaries, key points and the editor’s take are written by software from other outlets’ reporting and may contain errors — always check the linked original."
}