开发者在编写文档方面很糟糕。我们喜欢说 RTFM，但通常根本没有 FM 可以 R。至多我们拥有一堆粗略的笔记、一点过时的提示，以及一个荒凉论坛的链接，里面满是人们一次又一次地问同样的问题。这可不是对待我们的用户的好方式。我天真地相信有更好的方法。正如我之前所写的那样，你应该坐下来真正测试一下你的 README。启动一个新的虚拟机，逐一检查你所写的内容，看看它是否有意义。但真的很难忽视自己的偏见。当然，你知道某些命令需要 sudo，显然当你写 -foo 时，你的意思是 --foo，大家都知道你必须重启之后。你如何摆脱这些偏见？我付钱给人们！作为我 NLnet 资助申请的一部分，我说我想测试真实用户的安装体验，我准备为他们的一个小时提供 25 欧元。我在 Mastodon 发布了这个邀请，聚集了一些人，并与他们进行视频通话。格式很简单。我解释说我在寻找关于首次运行体验的反馈。我知道这不是完美的，并且积极希望得到建设性的批评。我让志愿者分享他们的屏幕，并且至关重要的是，要大声说出来。告诉我他们在做什么，什么是他们不理解的，什么让他们困惑，什么让他们高兴，什么让他们沮丧，等等。我手写了笔记（去你妈的机器）并花了几个小时被告知我犯了什么错误的假设。我发现的亮点包括：演示工具的链接是错误的。有些人是在终端中阅读 README 的。重命名文件实际意味着什么？如何重命名一个隐藏文件？演示工具应该在网上可用，还是仅在用户的本地计算机上可用？为什么有些文本需要被明确引用而有些则不需要？我的笑话不好笑，实际上让人困惑。一些技术术语需要解释。不同部分的顺序让人困惑。我并没有真正解释软件会做什么。一个从技术上对我来说很有趣的部分对所有其他人来说都是完全困惑的。并非所有 Web 服务器以相同的方式使用权限。接下来就是这样！每次会议后，我根据人们发现的困难更新 README，然后再次测试下一个人。总的来说，我支付了大约 150 欧元让一群人当面批评我。嘿，比心理治疗便宜，对吧？我知道总有人会问：“为什么不请 LLM 模拟一系列用户？”答案很简单——我想和真实的人交谈。人们真是太棒了！他们能让你笑，当他们的猫在通话时走过的时候你能看到他们，带来独特的视角，并且当你给他们一个 25 欧元的代金券时，他们真的很高兴。有些人愿意免费做，让你开心！当我为 GOV.UK 做技术写作时，我所有美丽的散文都被另一个人进行了二次审阅。他们把我所有的华丽词句都剖析掉，把文档变成更易读的版本。他们是唯一能发现那些任何拼写检查器都无法捕捉的错误的人。他们能够与我进行正常的对话。更重要的是，我能听到他们语气中的沮丧——这是让你知道错误需要被纠正的东西。我并不声称 ActivityBot 的 README 现在是完美的——远非如此——但它现在确实更容易遵循了。开发者需要与真实的人交谈。如果你负担不起，你不必付钱——但找到一些人，在他们尝试遵循你的指示时大声说出来。我保证，你的 README 会因此变得好得多。