开发者经常编写糟糕的文档，假设用户与他们有相同的偏见和知识。为了克服这一点，作者付费让真实用户每小时 25 欧元测试他们的 Activity Bot README，通过大声遵循说明并共享屏幕。这揭示了关键缺陷：损坏的演示链接、令人困惑的文件重命名步骤、不明确的技术术语、章节顺序不佳以及未解释的软件目的。作者做了手写笔记，在每次会话后更新 README，并用新用户重新测试。经过多次会话，他们为坦率反馈支付了 150 欧元。这一过程凸显了真实用户如何暴露隐藏的假设——比如 sudo 需求、重启要求和引用规则——这些是开发者容易忽视的。与 LLMs 不同，真实的人带来幽默、独特视角和情感线索，如挫败感，这些能指示文档失效的地方。作者将此与他们在 GOV.UK 的技术写作经验进行比较，在那里人工审查将花哨的散文转化为清晰可用的文档。虽然 README 仍不完美，但现在显然更易遵循。核心教训是：开发者必须让真实的人大声思考地测试文档，即使无偿，以发现盲点并提升可用性。
来源: Hacker News · 由HeadlinesBriefing整理摘要