我花钱请人照着我的 README 操作一遍
文章摘要
Terence Eden 是英国的开发者和博主，曾在 GOV.UK 做技术写作。这篇 700 字左右的短文讲的是他如何改进自己的开源项目 ActivityBot（一个用 PHP 写的 ActivityPub 机器人工具）的 README。
开发者写文档普遍很烂。 他开篇就自我批评：”我们爱说 RTFM（去读该死的手册），可很多时候根本没有手册可读。”最好的情况也不过是一堆潦草笔记、几条过时的小技巧，外加一个荒凉论坛的链接，里面全是人在重复问同样的问题。他之前就写过文章主张开发者应该亲自测试 README：开一台全新虚拟机，照着自己写的东西走一遍，看看说不说得通。
但自己的偏见很难绕开。 你当然知道某些命令要加 sudo，你写 -foo 时显然想说的是 --foo，而且”谁都知道”装完要重启。怎么摆脱这些偏见？他的答案是：花钱请人。
做法。 在为 ActivityBot 申请 NLnet 资助时，他就写明要用真实用户测试安装体验，并准备为每人一小时的时间支付 25 欧元。他在 Mastodon 上发了招募帖，找到几个人，逐一视频通话。形式很简单：他先说明自己想要的是首次使用体验的反馈，知道它不完美，诚心希望听到建设性批评；然后请志愿者共享屏幕，最关键的是边做边说出来，讲出自己在做什么、哪里不懂、什么让人困惑、什么让人高兴、什么让人烦躁。他手写笔记（原文是一句粗口：”去他的，不喂机器”），花了好几个小时听别人告诉他自己做了哪些错误的假设。
发现的问题 包括：演示工具的链接是错的；有人在终端里读 README；”重命名一个文件”到底是什么意思；隐藏文件怎么重命名；演示工具应该放在网上还是只在用户本机运行；为什么有些文本要加引号有些不用；他的笑话不好笑，还会把人搞糊涂；一些技术术语需要解释；各章节的顺序令人困惑；他根本没说清楚这个软件是干什么的；有一整节他自己觉得技术上很有意思，其他人全都看不懂；不同 Web 服务器处理权限的方式并不一样。每次测试结束，他都根据对方遇到的困难修改 README，再拿去给下一个人测。总共花了约 150 欧元，”让一群人当面批评我，比心理治疗便宜，对吧？”
为什么不让 LLM 模拟用户？ 他预料到会有人这么问，回答很简单：他想和真人交谈。人很棒，能逗你笑，猫会走进镜头，他们会带来独特视角，拿到 25 欧元代金券时会很开心，有些人甚至乐意免费帮忙。他回忆在 GOV.UK 写技术文档时，所有”漂亮文字”都要经过另一个人审读，对方会把华丽辞藻砍得干干净净，让文档更易读，还能抓出”拼写检查器（spell chequer）抓不到的错误”（这是个双关笑话，chequer 本身是合法英式单词，所以拼写检查不会报错）。更重要的是，他能听出对方语气里的沮丧，那才是一个错误必须改正的信号。
他承认 ActivityBot 的 README 远谈不上完美，但现在已经明显更容易照着做。结论是：开发者需要和真人交谈。付不起钱也没关系，找几个人边照着说明操作边大声说出想法，”我保证你的 README 会因此好很多”。
HN 评论精华
本帖 429 分、200 多条评论。讨论主要围绕：这本质上就是可用性测试；README 该假设读者具备哪些前提；README 里的表情符号和笑话；能否用 LLM 代替真人测试；以及”README 不说软件是干什么的”这一普遍顽疾。作者 edent 本人也在评论区积极回应。
这就是可用性测试。 coo1estguy 说这以前叫”雇 QA 找项目的漏洞”。nkrisc、bryanhogan、sbarre 都指出这正是 UX 领域的可用性测试，坐在旁边看用户走完你设计的流程，给报酬也很正常；nkrisc 提到通常不会在每个参与者之后修改被测对象，但对 README 这种小众场景来说，不那么严谨也无妨。bryanhogan 推荐了 Nielsen Norman Group 的可用性测试入门文章。bambax 说他记得第一个用户就能发现一半问题，五个用户能发现近九成，citelao 纠正说 NN/g 的数据是第一个用户约 31%；nkrisc 说他待过的 UX 团队都用 6 名参与者，再多收益就急剧递减。sbarre 点出技术文档的一个讽刺：通常是专家被拉来写文档，可他们写出来的东西是给同等水平的人看的，而不是给目标读者看的。iamflimflam1、michael（原文评论区）说过去入职的标准流程就是让新人照着 README 搭环境并修正问题。
README 要从多底层讲起？ WhyNotHugo 指出 README 的快速入门少了”第零步”：安装和配置 php-fpm，并让 Web 服务器把它当作后端。edent 回应这很棘手：”要回溯到技术栈的哪一层？要不要教人用 git 检出代码？”layer8、astura 说这就是”先决条件”一节的用途，不必教怎么装，但要列出来；edent 贴出了 README 里的先决条件列表，其中一条是”不需要 Adobe Creative Cloud”，airstrike 觉得很有趣，subscribed 则认为这是在开玩笑而不是认真列先决条件。BoppreH 分享自己的经验法则：README 应包含一串命令，在干净的机器上依次执行就能让软件做出有用的事，包括 git clone；mr_mitm 追问为什么不从 apt install git 讲起，引来一串”先从如何把硅做成晶体管讲起”“想从零做苹果派，你得先发明宇宙”的玩笑。patrickmay、Neywiny 建议提供 Dockerfile 或 docker compose，sshine 则说用 Nix 加 direnv，新人三步就能拿到完整工具链，”在可以程序化配置整个工具链的时代，往 README 里写错误信息已经过时了”。
表情符号和笑话。 最高票的评论来自 commandersaki，他讨厌满是表情符号的 README；layer8 说这会让他立刻离开，cowlevel、ivanjermakov 认为这是 LLM 生成的标志，Kiro 反驳说这在 LLM 出现之前就流行了，可能是 Notion 带起来的。edent 回应，测试中大约一半参与者喜欢表情，一人不喜欢，其余没有明显偏好，他保留是因为”它们让我开心”；bookofjoe 一针见血：”重点不是让你的用户开心吗？没人在乎你开不开心。”关于”我的笑话不好笑还让人困惑”这句，很多人觉得这句话本身就很好笑。fmx 举了 rms 在 glibc 手册 abort() 一节里写的联邦审查笑话引发争议的例子：只有美国人看得懂，其他人只会困惑，”人们读手册是为了尽快完成工作，不是来找乐子的”；mrheosuper 回应他小时候就是因为无聊才读手册。kens 认真考证了”spell chequer”这个梗，最后感慨：”我明白为什么大家觉得他的笑话让人困惑了。”bartread 讲了一段长长的往事：他在 Redgate 时用蒙提·派森台词做测试版过期提示，后来用美剧《豪斯医生》里猜女友的对白做反破解的错误提示，结果被 Greg Young 发到网上疯传，最后只好把错误信息改成编号。
LLM 能代替真人吗？ badsectoracula 认为作者花钱买的其实是”和人交流”，检查 README 本身是次要的，任何像样的 LLM 都能检查说明是否可执行。amirkhanian 说智能体和人发现的问题不同，他的 AI 审查者能找到”手指按在摇杆上时双指缩放失效”这样的真 bug，但没有一个说过”这很无聊”。tilemarch 让 20 个带不同身份的子智能体照着文档玩游戏，发现它们卡住的地方和人类一样，但智能体不会告诉你文档令人困惑，”它只会满怀信心地做错事，而电话里的人会说’等等，什么？’，这就值 25 欧元”。piro0919（用 AI 从日语翻译）总结得很简洁：”AI 测 UI，人测 UX。”calmingsolitude 说 LLM 很擅长读 README，写起来却糟透了。dawnerd 看到仓库里有 agents.md 就认定 README 是 LLM 写的；edent 指出项目明确声明不使用 AI，那个文件本身就是个劝退 AI 的玩笑，dawnerd 去看了以后承认”有道理”。
最常见的毛病：不说软件是干什么的。 这是作者的发现之一，也引起了最多共鸣。alienbaby、extralongdivisi、joshuaS98、fastaguy88、GarnetFloride 都说经常遇到”某某是用某语言写的某某流行词某某流行词”这种 README，GarnetFloride 甚至见过一个连自己叫什么都没写的；jllyhill 补充另一种变体”Foo 是 Bar 的替代品”。andai 吐槽很多开发者产品的官网只写”Gleam 是你 Fork 的 Tribble！”，epistasis 给出一个有趣解释：这种页面是写给要批准采购的财务部门看的。bambax 说他给自己写的 README，几周后自己都看不懂了；dofm 建议为”四五年后更老、更累、更没耐心、对现在这个自以为记性好的年轻人更没好感的自己”写文档。adrianmonk 把写文档类比为写代码：每句话都是改变读者头脑状态的一个操作，要知道初始状态，不能引用未定义的符号，不能留下未初始化的值，”要在脑子里扮演读者”。
少数批评。 astura 很不客气，认为作者说的那些”偏见”其实只是没有认真照着自己的文档做，他自己测文档时总是逐字复制粘贴，从未漏过这类错误。fartfeatures 和 ballon_monkey 则对”去他的，不喂机器”那句话很反感，认为作者在电脑上写博客却装作反感机器是为了博眼球。还有 seqizz 抱怨博客在手机 Firefox 上无法阅读，结果是之前误点了网站主题切换器里的”醉酒模式”，edent 亲自出来解释。