I paid people to try and follow my README

Developers suck at writing documentation. We like to say RTFM but often there ain’t no FM to R. At best we have a half-arsed collection of notes, some obsolete tips, and a link to a desolate forum full of people asking the same questions again and again. That’s no way to treat our users.

开发者在编写文档方面很糟糕。我们喜欢说“去读手册”（RTFM），但往往根本就没有手册可读。我们充其量只有一堆敷衍了事的笔记、一些过时的技巧，以及一个荒凉论坛的链接，里面全是人们反复询问同样的问题。这不是对待用户应有的方式。

I naïvely believe there’s a better way. As I’ve written before, you should sit down and actually test your readme. Spin up a fresh Virtual Machine, go through what you’ve written, and see if it makes sense.

我天真地认为有更好的方法。正如我之前写过的，你应该坐下来亲自测试你的自述文件（README）。启动一台全新的虚拟机，按照你写的内容操作一遍，看看它是否通顺合理。

But it is really hard to ignore your own biases. Of course you know that certain commands require sudo and obviously when you wrote -foo you meant —foo and everyone knows that you have to reboot afterwards.

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

How do you get rid of those biases? I paid people!

你如何摆脱这些偏见？我付钱请人来做！

As part of my NLnet grant application for ActivityBot, I said I wanted to test the install experience with real users and I was prepared to pay them €25 for an hour of their time. I stuck out the call on Mastodon, gathered a few people, and had a video call with them.

作为我为 ActivityBot 申请 NLnet 资助的一部分，我说我想用真实用户测试安装体验，并准备为他们的一小时时间支付 25 欧元。我在 Mastodon 上发出了邀请，召集了几个人，并与他们进行了视频通话。

The format was simple. I explained that I was looking for feedback on the first-run experience. I knew that it wasn’t perfect and actively wanted constructive criticism. I asked the volunteer to share their screen and, crucially, to speak aloud. Tell me what they were doing. What they didn’t understand, what confused them, what delighted them, what frustrated them, etc.

形式很简单。我解释说我正在寻求关于首次运行体验的反馈。我知道它并不完美，并积极寻求建设性的批评。我请志愿者分享他们的屏幕，最重要的是，请他们大声说出来。告诉我他们在做什么。他们不理解什么，什么让他们困惑，什么让他们高兴，什么让他们沮丧，等等。

I took notes by hand (fuck feeding the machine) and spent several hours being told what incorrect assumptions I’d made.

我用手做笔记（去他的机器录入），花了几个小时听别人指出我做了哪些错误的假设。

Amongst the highlights I discovered were:

我发现的重点包括：

After each session I updated the README based on what people found difficult, then I re-tested it with the next person.

在每次会话后，我根据人们觉得困难的地方更新了 README，然后与下一个人重新测试。

In total, I paid out around €150 to have a bunch of people criticise me to my face. Hey, cheaper than therapy, right?

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

I know someone is going to say “why not just ask an LLM to simulate a range of users?” The answer is very simple - I want to speak to real people. People are brilliant! They can make you laugh, you can see their cat when it wanders on to the call, they bring a unique perspective to the problem, and they’re really happy when you give them a €25 voucher. Some will gladly do it for free and make you happy!

我知道有人会说“为什么不直接让大语言模型（LLM）模拟各种用户呢？”答案很简单——我想和真实的人交谈。人是了不起的！他们能让你发笑，当他们的猫闯入通话时你能看到它，他们为问题带来了独特的视角，当你给他们 25 欧元的代金券时他们会非常高兴。有些人甚至乐意免费做这件事，让你感到快乐！

When I was doing technical writing for GOV.UK, all my beautiful prose was given a second-eye by another human. They eviscerated all my flowery phrases and turned the document into something more readable. They were the ones who caught the mistakes that no spell chequer could. They were able to have a proper conversation with me. More importantly, I could hear the frustration in their voice - that’s the thing which lets you know a mistake needs to be corrected.

当我在为 GOV.UK 做技术写作时，我所有优美的散文都会由另一个人进行二次审阅。他们删除了我所有华丽的辞藻，使文档变得更易读。他们发现了任何拼写检查器都无法捕捉到的错误。他们能够与我进行适当的对话。更重要的是，我能听到他们声音中的挫败感——这正是让你知道错误需要纠正的地方。

I don’t claim that ActivityBot’s README is now perfect - far from it - but it is now demonstrably easier to follow. Developers need to talk to real people. You don’t have to pay them if you can’t afford it - but find a few people who will talk aloud while they try to follow your instructions. I guarantee you that your README will become much better for it.

我并不声称 ActivityBot 的 README 现在完美无缺——远非如此——但它现在明显更容易遵循了。开发者需要与真实的人交谈。如果你负担不起，不必付钱给他们——但请找几个人，让他们在尝试遵循你的说明时大声说出想法。我保证你的 README 会因此变得好得多。

Enjoyed this post? Show your support and pay the author.

喜欢这篇文章吗？表达你的支持并向作者付费。

I paid people to try and follow my README | Hacker News

我付钱请人尝试遵循我的 README | Hacker News

Reply | Reply to original comment 2026-10-11 12:01

回复 | 回复原始评论 2026-10-11 12:01

Oh, this is great. In an ideal world we’d see specific grants available to support this kind of thing (and documentation writing in general, although ISTR that some of the OSS grant giving has documentation as a category).

哦，这太棒了。在理想的世界里，我们希望能看到专门的资助来支持这类事情（以及一般的文档编写，尽管我记得一些开源资助确实将文档列为一个类别）。

Reply | Reply to original comment on bsky.app 2026-10-11 13:44

回复 | 回复 bsky.app 上的原始评论 2026-10-11 13:44

I occasionally catch workflows that turn sequences of ”—” into em-dashes, producing documentation like

that are just borked, but happen in the conversion from markup to output, so are hard to catch while authoring 😃

我偶尔会发现一些工作流将 ”—” 序列转换为长破折号（em-dashes），从而产生像这样的文档：

这些文档完全坏掉了，但它们发生在从标记语言到输出的转换过程中，因此在编写时很难发现 😃

Reply | Reply to original comment on mastodon.bsd.cafe 2026-10-11 14:49

回复 | 回复 mastodon.bsd.cafe 上的原始评论 2026-10-11 14:49

@Edent Ha, I ONLY read a README in the terminal. If I’m reading a README, it’s because I’m installing something. In the terminal. READMEs with markdown or HTML or something are so irritating. So good catch on that one.

@Edent 哈，我只在终端里读 README。如果我在读 README，那是因为我正在安装东西。在终端里。带有 Markdown 或 HTML 之类的 README 太烦人了。所以这一点抓得很好。

Reply | Reply to original comment on sfba.social 2026-10-11 16:20

回复 | 回复 sfba.social 上的原始评论 2026-10-11 16:20

Hi @Edent 💯 - #UX tests are in fact inevitable for everything that you care can be used by others than yourself. The way explained e.g. in Stephen Krug’s ‘Don’t make me think’. ‘Everything’ including, but not limited to, all(!) user facing material, docs, readmes, online resources, etc.

Excluded only, what you don’t care anybody else can make use of. Which may mean, you can skip it altogether.

嗨 @Edent 💯 - 对于任何你希望除自己以外的人也能使用的东西，#UX（用户体验）测试实际上是不可避免的。正如 Stephen Krug 在《点石成金》（Don’t make me think）中所解释的那样。“一切”包括但不限于所有（！）面向用户的材料、文档、README、在线资源等。

唯一排除的是那些你不在乎别人是否能使用的东西。这意味着，你可以完全跳过它。

Reply | Reply to original comment on digitalcourage.social 2026-10-11 16:36

回复 | 回复 digitalcourage.social 上的原始评论 2026-10-11 16:36

“They were the ones who caught the mistakes that no spell chequer could”

“他们发现了任何拼写检查器都无法捕捉到的错误”

Reply | Reply to original comment on indieweb.social 2026-10-11 17:24

回复 | 回复 indieweb.social 上的原始评论 2026-10-11 17:24

@Edent absolutely! I have heard this described as “hallway testing” (q.v. https://duckduckgo.com/?q=hallway%20usability%20testing&ko=-1&ia=web), which is a form of “usability testing” (q.v. https://en.wikipedia.org/wiki/Usability_testing).

I know that my code requires unit tests before I will be confident in it. Why should I be confident in my documentation without tests?

@Edent 绝对如此！我听说这被称为“走廊测试”（参见 https://duckduckgo.com/?q=hallway%20usability%20testing&ko=-1&ia=web），这是“可用性测试”（参见 https://en.wikipedia.org/wiki/Usability_testing）的一种形式。

我知道我的代码需要单元测试我才会对其有信心。为什么我在没有测试的情况下就该对我的文档有信心呢？

Reply | Reply to original comment on mstdn.ca 2026-10-11 18:21

回复 | 回复 mstdn.ca 上的原始评论 2026-10-11 18:21

Love the spell check gag!

(Yours, terrible at documents AND terrible at proofreading own prose guy.)

喜欢那个拼写检查的梗！

（来自一个既不擅长写文档，又不擅长校对自己文章的人。）

Reply | Reply to original comment on bsky.app 2026-10-11 18:56

回复 | 回复 bsky.app 上的原始评论 2026-10-11 18:56

All comments are moderated and may not be published immediately. Your email address will not be published.

所有评论均经过审核，可能不会立即发布。您的电子邮件地址不会被公开。

Posted a response on your own website? Share the link here:

	Your post must include a link to this post.

Drag the nodes to rearrange them.

在您自己的网站上发布了回复？在此分享链接：

您的文章必须包含指向此帖子的链接。

拖动节点以重新排列它们。