Developers often write poor documentation, assuming users share their biases and knowledge. To overcome this, the author paid real users €25 per hour to test their Activity Bot README by following instructions aloud while sharing their screen. This revealed critical flaws: broken demo links, confusing file renaming steps, unclear technical terms, poor section ordering, and unexplained software purpose.
The author took handwritten notes, updated the README after each session, and retested with new users. Over several sessions, they paid out €150 for candid feedback. The process highlighted that real users expose hidden assumptions—like sudo needs, reboot requirements, and quoting rules—that developers overlook.
Unlike LLMs, real people bring humor, unique perspectives, and emotional cues like frustration, which signal where documentation fails. The author compares this to their GOV. UK technical writing experience, where human review turned flowery prose into clear, usable docs.
While the README isn’t perfect, it is now demonstrably easier to follow. The core lesson: developers must test documentation with real people who think aloud, even if unpaid, to uncover blind spots and improve usability.
Source: Hacker News · Summarized by HeadlinesBriefing