READMEを読んでもらうために人に報酬を払ってみた

開発者はドキュメントを書くのが下手だ。 RTFM（Read The F***ing Manual）と言うのは好きだが、しばしば読むべきマニュアルが存在しない。 せいぜい、半端なメモの寄せ集め、時代遅れのヒント、そして同じ質問が何度も繰り返される寂れたフォーラムへのリンクがあるだけだ。 それはユーザーを扱う方法ではない。 私はナイーブにも、もっと良い方法があると信じている。 以前書いたように、あなたは座って実際にREADMEをテストすべきだ。 新しい仮想マシンを起動し、書いた内容を最初から最後まで実行して、それが意味をなすか確認するのだ。 しかし、自分のバイアスを無視するのは本当に難しい。 もちろん、特定のコマンドにはsudoが必要であることや、明らかに-fooは--fooを意味していたこと、そしてその後再起動が必要なことは誰もが知っている。 どうすればこれらのバイアスを取り除けるだろうか？ 私は人々にお金を払った！ ActivityBotのためのNLnet助成金申請の一部として、私は実際のユーザーでインストール体験をテストしたいと述べ、1時間の時間に対して25ユーロを支払う用意があると伝えた。 Mastodonで呼びかけを行い、数人を集め、彼らとビデオ通話をした。 形式はシンプルだった。 私は、最初の実行体験に関するフィードバックを求めていると説明した。 完璧ではないことを知っており、建設的な批判を積極的に求めていた。 ボランティアに画面を共有してもらい、そして最も重要なことに、声に出して話してもらうように頼んだ。 彼らが何をしているか、何が理解できなかったか、何が混乱したか、何が喜ばしかったか、何が不満だったかなどを話してもらった。 私は手書きでメモを取り（機械に餌を与えるのはクソだ）、私が犯した誤った仮定について数時間聞かされた。 ハイライトの中には、デモツールへのリンクが間違っていたこと、一部の人はターミナルでREADMEを読むこと、ファイル名を変更するとは具体的にどういうことか、隠しファイルをどうやってリネームするか、デモツールはウェブで利用可能にすべきか、それともユーザーのローカルマシンだけで良いのか、なぜ一部のテキストは引用符で囲む必要があり、一部はそうでないのか、私のジョークは面白くなく、むしろ混乱を招くこと、一部の技術用語には説明が必要であること、セクションの順序が混乱していること、ソフトウェアが何をするのかを説明していなかったこと、私にとって技術的に興味深いセクションが他の人には全く理解できなかったこと、すべてのWebサーバーが同じようにパーミッションを使用しているわけではないこと、などがあった！ 各セッションの後、人々が見つけにくかった点に基づいてREADMEを更新し、次の人と再テストした。 合計で、私は約150ユーロを支払って、たくさんの人々に私の顔を見て批判してもらった。 まあ、セラピーより安いだろう？ 誰かが「なぜLLMに様々なユーザーをシミュレートさせないのか？」と言うだろう。 答えは非常にシンプルだ - 私は実際の人々と話したいのだ。 人々は素晴らしい！ 彼らはあなたを笑わせることができるし、電話中に猫が通りかかればそれを見ることができるし、問題に対してユニークな視点をもたらしてくれるし、25ユーロのバウチャーを渡すと本当に喜んでくれる。 一部の人は喜んで無料でやってくれて、あなたを幸せにしてくれるだろう！ GOV.UKのテクニカルライティングをしていたとき、私の美しい文章はすべて別の人間によってセカンドアイ（二重チェック）されていた。 彼らは私の装飾的なフレーズをすべて削除し、ドキュメントをより読みやすいものに変えた。 彼らはスペルチェッカーでは見つけられない間違いを見つけてくれた。 彼らは私とまともな会話をすることができた。 さらに重要なのは、彼らの声のフラストレーションを聞くことができた - それは間違いを修正する必要があることを知らせてくれるものだ。 ActivityBotのREADMEが今や完璧だとは主張しない - それどころか - しかし、それは証明できるようにフォローしやすくなった。 開発者は実際の人々と話す必要がある。 もし余裕がなければ、彼らにお金を払う必要はない - しかし、指示に従いながら声に出して話してくれる人を数人見つけてほしい。 そうすれば、あなたのREADMEは間違いなくずっと良くなるだろう。 この投稿をシェアする… news.ycombinator.com I paid people to try and follow my README | Hacker News 返信 | 元のコメントに返信 2026-10-11 12:01 Mastodonでのコメントをもっと見る。