ハクソク

世界を動かす技術を、日本語で。

READMEに従おうとした人々に報酬を支払った

2026年10月11日原文(shkspr.mobi)

概要

開発者のドキュメント作成の苦手さ とその課題を指摘。 READMEの実際のユーザーテスト の重要性を強調。 バイアス排除のための有償テスト の実施例を紹介。 ユーザーの生の声による改善点 の発見。 AIではなく実際の人間との対話 の価値を強調。

開発者とドキュメント作成の現状

  • 開発者はドキュメント作成が苦手 という現実
  • RTFM（マニュアルを読め）と言いがち だが、そもそもマニュアルがない場合が多い
  • 断片的なメモや古い情報、孤立したフォーラム が頼り
  • ユーザーへの配慮不足 が現状
  • より良い方法がある という信念

READMEの実際のテストのすすめ

  • READMEを自分でテストする重要性
  • 新しい仮想マシンを使って手順を検証 する方法
  • 書き手自身のバイアス （sudoの必要性やコマンドの書き間違い、再起動の必要性など）に気付きにくい問題

バイアス排除のための有償ユーザーテスト

  • ActivityBotのインストール体験を実ユーザーでテスト
  • NLnetの助成金申請の一環 として実施
  • 1時間25ユーロで参加者を募集
  • Mastodonで呼びかけ、ビデオ通話形式で実施
  • 初回体験のフィードバックを重視
  • 画面共有と声に出しての実況 を依頼
  • 理解できない点や混乱点、嬉しかった点、苛立ちなどをリアルタイムで収集
  • 手書きでメモを取り、機械には頼らない姿勢

テストで得られた主な気づき

  • デモツールのリンクの間違い
  • READMEをターミナルで読む人がいる事実
  • ファイル名変更の説明不足や隠しファイルの扱い
  • デモツールのWeb提供かローカル提供かの疑問
  • 引用符の要否が不明瞭
  • ジョークが混乱の元になる場合
  • 技術用語の説明不足
  • セクションの順序が分かりづらい
  • ソフトウェアの具体的な動作説明の欠如
  • 開発者にとって面白いがユーザーにとっては混乱する内容
  • Webサーバーごとに異なる権限設定
  • セッションごとにREADMEを改善し、次のユーザーで再テスト

実ユーザーと対話する価値

  • 合計約150ユーロを費やし、直接フィードバックを受けた経験
  • AIやLLMではなく実際の人間との対話の重要性
  • 人間ならではの視点やユーモア、リアルタイムの反応
  • 25ユーロのバウチャーで喜ぶ参加者
  • 無料で協力してくれる人も存在

他者によるレビューの価値

  • GOV.UKでの技術文書執筆経験
  • 他者によるチェックで美辞麗句が削ぎ落とされ、可読性向上
  • 機械では検出できない誤りの発見
  • 会話を通じてフラストレーションの声を直接聞ける利点

README改善のすすめ

  • ActivityBotのREADMEは完璧ではないが、明らかに分かりやすくなった事実
  • 開発者は実際の人と話すべき
  • 報酬が出せなくても、声に出して手順を追ってくれる人を探す価値
  • READMEの質が確実に向上することを保証

Hackerたちの意見

以前は「QAの人を雇ってプロジェクトの隙間を見つけてもらった」って言ってたけど、今や「READMEを読んでもらうためにお金を払う」になっちゃったね。

└

これ、まさにUXのユーザビリティテストみたいだね。誰かと一緒に座って、その人が作ったプロセスを進めるのを見守る感じ。時間を払うのは普通のことだよね。でも、参加者ごとに内容を修正するのは普通じゃないかな。ただ、READMEを追うみたいなニッチな内容なら、少し緩くても大丈夫かも。

「私のジョークは面白くなくて、逆に混乱させちゃう。昔は技術文書を散文スタイルで書いてたけど、たまに話が逸れちゃうこともあった。初めてブログを書いてた頃にそのスタイルを身につけたのかな。読み返すのが嫌になったから、もっと簡潔にしようとした。時々、ちょっとした色を加えることもあるけど、メインメッセージを邪魔しない範囲でね。」

└

短くて簡潔にまとめるのが一番だよね。私は文脈を詳しく説明したくて、つい長くなっちゃうけど、短くて正確な方がいい。多くの開発者もそれが苦手だし、動作する例がないプロジェクトも多い。それが一番イライラする。新しいユーザーが私のプロジェクトの使い方を学ぶことに興味がないってメッセージを送ってるみたい。

└

これって脚注のためじゃないの？

└

「私のジョークは面白くないし、逆に混乱させる。まあ、その投稿の中のその文はすごく面白かったけど ;-)」

└

ドキュメントのスタイルを決めるとき、私はチュートリアルとリファレンスの線引きをすることが多い。導入ガイドの線形なトップダウンの流れは、トピックから外れても追加のコンテキストを入れやすいけど、APIやハードウェアのリファレンスでは、各セクションを自己完結させて、簡単に検索できるようにするのが一般的だよね（キーワードを慎重に選ぶことで誤ったヒットを最小限に）。私は、チュートリアル全体をコードとして書くリテラルプログラミングのアプローチがこの目的にかなり効果的だと感じていて、いくつかの自分のプロジェクトでうまく活用してるよ。

これはUXデザインの分野で言うユーザビリティテストにすごく近いね。Nielson Norman Groupの良い入門記事があるよ：https://www.nngroup.com/articles/usability-testing-101/ HNの人たちにとって興味深いかな？私はコーディングとデザインのミックスを専攻してた。

└

うん、すごくそう思うし、リンクありがとう。

└

どこかで読んだ気がするけど（実際、私の経験とも合ってる）、最初のユーザーが50%の問題を見つけて、5人のユーザーで90%近くを見つけられるって。だから、人間のテストはほんとに貴重で、得られるメリットに対してかなり安いんだよね。

ドキュメントはめっちゃ大事だよね。私はドキュメントをコードと同じように扱ってる。mkdocsが結構うまく機能して、メインブランチに変更をコミットするときにドキュメントを更新するGitHubジョブと統合してる。貢献者がエラーを修正したり、役立つ指示を追加できるのもいいね。ただ、自分のバイアスにあまり注意を払ってない気がするから、プロセスを見てもらうために誰かを雇うのもいいかも。自分の指示はしっかりしてると思うけど、私ほど慣れてないユーザーにはどうかな。最適な方法でやってるかはわからないけど、長年いろんなドキュメントを使ってきたから、私がやったことは「ビッグテック」が提供するドキュメントへの不満を解消してると思う。

└

mkdocsはまだアイコンに「ウェブフォント」を使ってるんだよね。このハックはInternet Explorerとの互換性のために必要だったけど、今はただの流行りになっちゃってる。ウェブフォントを無効にするユーザー（読みやすさのために）にはアイコンが見えなくて、どこにでもユニコードのプレースホルダー（「豆腐」）が表示されるっていうアクセシビリティの問題がある。

Hacker Newsで議論の続きを見る