開発者の書く初心者向けチュートリアルは初心者にとってとにかく読みづらいという指摘に共感が集まる

プログラミングや開発などの技術初心者は、初期のチュートリアルとして、開発者の書いた解説や案内を参照することが多くあります。技術初心者にとって、多くの開発者が書くチュートリアルがいかに読みにくく理解しづらいものであるかを、作家のアニー・ミューラー氏が説明しています。

How I, a non-developer, read the tutorial you, a developer, wrote for me, a beginner - annie's blog
https://anniemueller.com/posts/how-i-a-non-developer-read-the-tutorial-you-a-developer-wrote-for-me-a-beginner

ミューラー氏は「開発者ではない私が、開発者であるあなたが初心者の私のために書いたチュートリアルをどのように読んだか」と題したブログで、「Very Simple Thing」という架空の開発について解説しています。ミューラー氏によると、Very Simple Thingは「クロマス」の「ジャグリング」はあるものの実に多用途で、「ピンタフォア」を「フーバスタンク」ではなく「クァグマイア」で「アーガイル化」することにしたとのこと。それはうまくいきましたが、「フィスターファンク」が「シャムロックポータル」と通信できず、ビープ音を「スナーフス」に送り返すことすらできないという壁にぶつかりました。「フーバスタンク」全体が「グラメリオン」で詰まってしまったため、裏側の「スナーファス・スタグネーター」を裏側の「シャムロック・クリンゴンエミュレーター」に接続したら改善できたとミューラー氏は記述しています。

そして、Very Simple Thingの設定方法を以下のように書いています。

1：ターミナルを開き、「ajkl;gawgor;iqeg;iJLkqen」を実行
2：次に「folder/hidden/deep/in/the/file/system/surprise!.file」に移動し、ファイルの内容をコピーします。
3：ターミナルに戻り、コピーした内容を貼り付けて「64A786AGR45JAR」と入力。
4：ここで「ピコーン！」と表示されたら成功です。
5：最後に「スナーファス」を起動し、作成したファイルをアップロードします。「—()()(]]asdg a=-do —cd go cd stay —sususudododo baby shark—][]」を実行して「クロノスタティオマトリックス」の「シャム」を解除することもできますが、これはオプションです。

これらの手順はミューラー氏が記述した架空のもので、「初心者にとって開発者のチュートリアルがどのように見えているか」をユーモアを交えて書いたものです。「Very Simple Thing(とてもシンプルなこと)」というタスクも、「シンプルな解説」と言いつつも難解な情報を提供するチュートリアルを皮肉したもの。

ミューラー氏は開発者の書くチュートリアルの問題について、「最初の3ステップを完了するために、およそ7時間にわたる193回のインターネット検索が必要になるでしょう」と述べています。要するに、初心者向けのチュートリアルにもかかわらず、解説に専門用語や固有名詞が説明なしに使われていると、解説を理解するための解説を読む必要が出てくるという問題です。

また、「コピーした内容をもとのファイルに貼り付ける」というだけの文章でも、ウェブ開発の文脈で書かれている場合は何らかの知識や操作を前提としていて、単なる文章やファイルのコピー＆ペーストとは異なるというようなケースもしばしば発生します。そのような「前提知識の省略」「当然のように使われている曖昧なコマンド」が、初心者を取り残しているとミューラー氏は指摘しています。

ブログの最後でミューラー氏は「これはジョークを交えた批評であり、知識を共有してくれる開発者には感謝しています」と前置きした上で、初心者を念頭に置いて「どこからが常識か」を慎重に判断して専門用語や具体的な手順を記述することの重要さを語りました。

ミューラー氏のブログはソーシャルニュースサイトのHacker Newsで話題になっており、「最低限の専門知識しか持たない人に、チュートリアルの目的達成を目指してドキュメントを読んでもらい、どこでつまずくのか見守るアプローチはオススメです」と初心者の視点が重要とする意見があります。専門知識を持つ人が他の人も同じ知識を持っていると思い込んでしまう現象を「知識の呪い」と表現するユーザーは、相手が話を半分しか聞いていないこと、聞き手が知らないかもしれない情報を言っている可能性を常に考えることを、重要なルールとしていると語っています。

さらに、ミューラー氏が指摘する問題は初心者特有のものではなく、ある程度経験や知識を持つ人であっても直面することがあると経験談を話すユーザーもいます。しばしば発生する問題として、新しいもののエコシステムがある程度成熟すると、そのエコシステム内の全員が持つ標準の知識が確立されて省略されていき、詳しく書かれた初期のチュートリアルにアクセスしづらくなるケースがあるそうです。