我花钱请人尝试按照我写的 README 进行操作，想看看别人能不能照着这份说明完成操作，而不是只由我自己来判断写得够不够清楚。我为此支付报酬，让他们一步步跟着指引做，并在 ActivityBot 与 ActivityPub 的语境下检验说明是否可行。

开发者写文档很糟糕。我们喜欢喊 RTFM（去读手册），却常常根本没有手册可读。往好了说，也只有一堆敷衍了事的笔记、几条过时的提示，以及一个冷清论坛的链接，里面的人翻来覆去问着同样的问题。这样对待用户可不行。

我天真地相信有更好的办法。正如我之前写过的，你应该坐下来，真的 测试一下你的 readme。开一台全新的虚拟机，照着自己写的内容走一遍，看它是否讲得通。

但要无视自己的偏见真的很难。你当然知道某些命令需要加 sudo，写 -foo 时你显然指的是 --foo，而且所有人都知道之后必须重启。

怎么消除这些偏见？我付钱找人！

在我为 ActivityBot 申请 NLnet 资助时，我曾表示想和真实用户一起测试安装体验，并愿意每小时支付 €25。我在 Mastodon 上发出招募，找到几个人，和他们进行了视频通话。

流程很简单。我说明自己想收集关于首次运行体验的反馈。我知道它并不完美，也非常欢迎建设性批评。我请志愿者共享屏幕，关键是让他们一边操作一边出声思考：告诉我他们在做什么，哪里看不懂、哪里感到困惑、哪里觉得惊喜、哪里让人沮丧等等。

我用手写笔记（去他的，绝不喂给机器），花了几个小时听他们指出我做出了哪些错误假设。

我从中发现的几个关键问题包括：

• 演示工具的链接是错的。
• 有些人是在终端里阅读 README 的。
• “重命名文件”到底是什么意思？
• 怎么重命名隐藏文件？
• 演示工具应该提供网页版，还是只在用户本地机器上运行？
• 为什么有些文本必须显式加引号，有些却不用？
• 我的笑话并不好笑，而且实际上让人困惑。
• 一些技术术语需要额外解释。
• 各个章节的排列顺序让人困惑。
• 我其实没有解释这个软件到底是做什么的。
• 有一整段内容对我这个作者来说技术上很有意思，但对其他人来说完全不知所云。
• 并非所有网页服务器都以同样的方式使用权限。

而且问题还远不止这些！

每次交流结束后，我都会根据大家觉得困难的地方更新 README，然后再找下一个人重新测试。

我总共支付了大约 €150，让一群人当面批评我。嘿，这比心理治疗便宜，对吧？

我知道有人会说：“为什么不直接让 LLM 模拟不同类型的用户呢？”答案很简单——我想和真实的人交谈。人是很棒的！他们会让你笑，猫踱步进视频画面时你还能看到它，他们会为问题带来独特的视角，而且当你给他们一张 €25 代金券时，他们会非常开心。有些人甚至乐意免费帮忙，反而让你感到开心！

我在 GOV.UK 做技术写作时，我那些漂亮的文字都会再由另一个人审阅。他们会把我所有华而不实的句子统统删掉，把文档改得更易读。他们是那些能发现拼写检查工具查不出错误的人。他们能和我进行真正的交流。更重要的是，我能从他们的声音里听出挫败感——正是这种感觉让你知道某个错误必须被修正。

我不敢说 ActivityBot 的 README 现在完美了——远非如此——但它显然比之前更容易照着做了。开发者需要和真实的人交流。如果负担不起，你不一定要付钱——但一定要找几个愿意一边照着你的说明操作一边出声思考的人。我敢保证，这样做会让你的 README 变得更好。

讨论整体认同 README 普遍糟糕、并肯定让不熟悉项目的人实际走查能暴露隐藏假设；分歧主轴在于：这种做法究竟是 UX 可用性测试般的必要投入，还是作者自己逐字执行文档、或用脚本/容器/LLM 自动化就能替代的伪需求。与此同时，社区对 README 里的 emoji 噪音、AI 生成垃圾，以及文章是否在给 LLM 文本“去 AI 味”明显存疑。

认为请真人照着 README 操作本质是可用性测试或摩擦日志，能暴露隐藏假设

• 多人指出，让外部用户或内部客户按文档真实走一遍，和 UX 领域的可用性测试、Stripe 式摩擦日志几乎是一回事：能发现作者自己看不见的命令/安装假设，也能推动工具被采用。（较多人）
• 文档作者常以为用户知道要加 sudo、知道 -foo 其实是 --foo、知道要重启，但真实用户并不会；连给自己写的备忘文档隔几周也会因丢失上下文而完全看不懂。 > 这非常接近 UX 设计领域里所说的可用性测试。（@bryanhogan）

认为文档糟糕的根源是作者陷入知识诅咒、缺少共情，且不说明项目用途

• 很多 README 读起来像假设读者已经会了，因为它们由已经懂的人写成；好文档需要像产品经理一样对读者有共情，而文档常被当作事后补充，水平一眼可见。（较多人）
• 常见毛病包括：不写软件到底解决什么问题，只给一串安装命令；遗漏环境前提，比如 PHP 项目默认读者已装好 php-fpm 并配好 http 服务；使用未解释的缩写；信息过时。 > 好的技术写作需要像好产品经理那样对用户有共情，而文档常被当成事后补充，所以水平一眼就能看出来。（@simonbarker87）

认为作者自己逐字照做文档就能发现问题，付钱请人检查并不必要

• 有评论尖锐指出，如果作者真的像客户一样原样复制粘贴命令、一步一步执行自己写的文档，那么漏 sudo、错参数、忘重启这类错误永远都能被发现，所谓“很难忽略自身偏见”并不是借口。（少数人）
• 在他看来，付钱请人、并确保对方不跳过文档，都不是必须的；自己认真走一遍就够，甚至可以自己按文档严格测试。 > 如果你真的按自己写的文档一步一步照做、原样复制粘贴命令，这些错误永远都能被发现，根本不用花钱请人。（@astura）

认为更好的做法是脚本化或容器化安装配置，而不是依赖人工读 README

• 多人认为，若一个程序还需要 README 才能安装使用，本质上仍像 Beta；各平台写个 shell、bat、make 或 cmake 脚本去自动配置依赖、构建安装并跑回归测试，只需几分钟，却能省下用户大量阅读时间。（较多人）
• Docker 在依赖上天生更稳，但仍有奇怪假设；更彻底的是用 Nix 搭配 direnv 以编程方式提供整个工具链，此时把易错信息写进 README 已经过时。 > 如果一个程序还需要 README 才能安装使用，它本质上还只是 Beta；给每个平台写个脚本自动配置，其实只要几分钟。（@Joel_Mckay）

认为 README 应该简短、像交换机，并克制 emoji 与 AI 腔调

• 一堆 emoji 被认为只是噪音；README 应当简短，充当把读者导向其他文档的“交换机”，连 FAQ 都被认为效果常不佳；写作上有人主张干货优先，只在不妨碍主旨时稍加人情味。（较多人）
• 此外，多数 README 应该配截图，命令行工具也一样，能帮人建立预期；有可运行示例的项目通常比没有示例的更容易上手。 > README 应该简短，像交换机一样把读者导向其他文档，而不是又长又带一堆 emoji 噪音。（@theletterf）

认为 AI 正在让 README 更糟，甚至怀疑本文是在给 LLM 生成稿“去 AI 味”

• AI 代理常把无关、难结合上下文的垃圾塞进 README，让上手更难；有人怀疑 README 一直都差，只是 AI 拉高了基线，生成的文本语言可能完美，但拼凑内容常无意义，读者现在看到就跳过或过滤。（较多人）
• 具体到本文，有评论看到 agents.md 后认为 README 很可能本来就是 LLM 吐出来的，目标只是别让它读起来像 AI 文本；一边说想和真人聊、一边清理 AI 垃圾，显得有点误导。 > AI 生成的文档虽然语言完美，但拼凑出的内容常常毫无意义，我现在看到就直接跳过或过滤掉。（@shevy-java）

认为 LLM 已能检查 README，付钱买到的主要是和真人交流

• 支持者转述作者动机：像样的 LLM（包括本地模型）都能检查 README 是否够用并给出改进建议，所以花钱买到的主要是和真人打交道——人会笑、会有猫入镜、带来独特视角，拿到 25 欧券还会开心，README 检查只是次要目的。（少数人）
• 这并不意味着否定雇佣真人，而是把“文档检查”和“用户共情/真人反馈”拆成了两件事。 > 其实像样的 LLM（包括本地模型）都能检查 README 是否够用并给出改进建议，作者付钱真正买到的其实是和真人打交道。（@badsectoracula）

有价值的补充

• 技术补充：用 Nix 搭配 direnv 可做到“安装 Nix 包管理器、装好 direnv 后在仓库执行 direnv allow、工具链/git hooks/MCP servers/仓库内 issue tracker 全部就位”，把整个工具链以编程方式提供给新人，从而不必把易错步骤写进 README。（@sshine）
• 方法补充：Stripe 使用的“摩擦日志”被推荐为平台团队与内部客户一起走查工具、推动采用并改进体验的具体做法；找 README 模板还可参考 Readme Driven Development、Readme.so，以及 HN 上“I’d like to review your README”等旧帖。
• 环境冷知识：PHP 项目文档常默认读者已有 php-fpm 并配置好 http 服务作为后端，却完全不提“安装 php-fpm、配置它、让 http 服务以它为后端”这一第零步，新手根本无从下手。（@WhyNotHugo）
• 一条纯玩笑：作者自嘲“我的笑话不好笑且令人困惑”，有读者回“你不必这样谋杀我！”（@andai），代表部分读者的轻松共鸣，也是社区里少数被保留的玩笑。