開発者がREADMEを実際にたどれるか、人を雇って試してもらった
I paid people to try and follow my README
開発者はドキュメントを書くのが苦手で、READMEはしばしば雑なメモの寄せ集めになる。自分では当然だと思っている前提や誤字に気づけないのが問題だ。そこで筆者はNLnetの助成を受けたActivityBotのインストール体験を検証するため、Mastodonで協力者を募り、1時間25ユーロを払って画面共有と思考の実況を依頼した。デモ用ツールのリンク切れ、隠しファイルのリネーム方法、説明されていない専門用語、順序の混乱など、次々と欠陥が見つかった。各セッションの後でREADMEを修正し、次の人に再テストを依頼。合計約150ユーロを費やして、実際に使う人の声から学んだ。
開発者は本当の人間と話す必要がある。お金がなければ無償でもいい。指示に従いながら声に出して考えを話してくれる人を何人か見つければいい。そうすればREADMEは必ずずっと良くなる。
HNでの議論
178- piro0919
半分は同意します。
私はClaude Codeでアプリを作っていて、PlaywrightでAIにUIをクリックさせてテストしています。仕様通りに動くか、壊れていないかを確認するにはそれで十分です。
でも、AIが試すときと人間が試すときでは目的が違うと思います。極端に言えば、AIはUIのためで、人間はUXのためです。ただ、人間もUIの問題を見つけます。私の音楽プレイヤーでは、実機のiPadのSafariで曲が再生できなくなり、自分で使ってみて初めて気づきました。この記事で見つかったこと、たとえばウケなかったジョークや、そのツールが何をするのかすら分からないといったことは、人間にしか見つけられない側面です。
（これは日本語で書いて、AIで翻訳しました。）
- bambax
> でも、自分のバイアスを無視するのは本当に難しい。特定のコマンドにはsudoが必要だと当然知っているし、-fooと書いたときは--fooのつもりだったのは明らかで、後で再起動が必要なことも誰でも知っている。
私は自分のためにreadmeを書くことがあります。データレポートを生成する正確な手順などを覚えておくためです。
ほんの数週間でどれだけ意味不明になるかには驚かされます。すべてが頭の中にあるときは、明確で流れるようで、自明なのです。しかし、いったんコンテキストを忘れてしまうと、何も意味をなさなくなります。
- andai
> そのソフトウェアが何をするのかを実際に説明していなかった。
最近見る投稿の半分はこんな感じだ。「Gleam 2.0。我々が学んだこと」とあって、ホームページに行くと「GleamはあなたのForkのためのTribbleだ！（下にスクロール）Gleam Enterpriseの対象かどうか確認しよう！」と書いてある。
- bryanhogan
これはUXデザインの分野でいうユーザビリティテストに非常に近いです。
Nielson Norman Groupが良い入門記事を出しています：https://www.nngroup.com/articles/usability-testing-101/
HNの人たちはこういうのに興味ありますか？
私はコーディングとデザインをミックスした専攻でした。
- extralongdivisi
> そのソフトウェアが何をするのかを実際に説明していなかった。
「<情報量のない名前>は<言語>で書かれた<buzzword> <buzzword>です」というパターンのREADMEをどれだけ読んだか、数え切れません。デモを使ったり見たりして初めて、それが何をするのかおぼろげに分かる程度です。しかも、そのデモがREADMEからは辿れないことがあまりにも多い。
- legacynl
これはいいですね。ほとんどのreadmeはひどいものです。一番ひどいのは、readmeにプロジェクトが何をするのか書かれていない場合だと思います。すべてのプロジェクトが一般向けとは限らないのは分かりますが、わざわざreadmeファイルを作る手間をかけるなら、なぜあと10センチだけ進んで、最も基本的な情報を書かないのでしょうか？
他の問題：
* 古くなった（つまり間違った）情報
* 導入されていない略語の使用（一般的な意味を持つ略語ならボーナス点、例：EG、NB、IE、ETC）
- trollbridge
これはLLMが本当に得意とするものの一つです。
新しいコンテナかサンドボックスを作り、gitリポジトリをコピーするかステージングドキュメントを指定して、何が起こるか見てみましょう。
- pinkmuffinere
> 私のジョークは面白くなく、積極的に混乱を招く。
:’)