初心者開発者の私が、あなた（開発者）が私のために書いたチュートリアルを読む方法

 (anniemueller.com)
5 ポイント 投稿者 GN⁺ 2025-09-23 | 1件のコメント | WhatsAppで共有
  • 初心者が開発者の書いた技術チュートリアルを読むときの混乱と壁を、ユーモラスに描いた文章
  • 開発者がよく使う専門用語や略語は、初心者にはまったく文脈のない「宇宙語」のように聞こえる
  • チュートリアルのインストール手順、ファイルパス、ターミナルコマンドなどが複雑すぎたり省略されていたりして、理解しにくい
  • 筆者は、開発者視点では当然の説明が、初心者には何時間もの検索と試行錯誤を要する障害になると指摘する
  • この文章は、チュートリアルを書く開発者に対して、初心者の視点でもっと親切かつ明確に説明すべきことを思い出させてくれる

文章の背景と問題意識

  • 筆者は開発者ではない初心者として、開発者が書いたチュートリアルを読みながら体験することを述べている
  • チュートリアルに登場する技術用語やツール名が何を意味するのかまったく見当がつかない状況を、風刺的に表現している
  • 例: Hoobijag、Snarfus、Shamrock portal のような架空の技術名を使い、初心者の目にはすべてが複雑に見えることを強調している

原文翻訳

「こんにちは！ 私は開発者です。私の関連する経験はこんな感じです。Hoobijag でコーディングし、ときどき jabbernocks も使います。もちろん ABCDE++++ もやります（でも絶対に ABCDE+/^+ ではありません、あれはありえないでしょう？ はは！）。それから Shoobababoo で作業するのが好きで、ときどき kleptomitrons も扱います。Company[1] で Shoobaboo 関連のコードを書くことになり、それが私を Snarfus へ導きました。さあ、始めましょう！

このチュートリアルについて

私は最初、Snarfus でとても簡単なこと[2]を始めたのですが、使えば使うほどその可能性が見えてきました！ chromus は少しこんがらがっていますが、実際にはとても多用途です。そこで私は hoobastank の代わりに quagmire で pintafore を argyling し始めたのです！ すごいでしょう、わかっています。でもある程度は動いたし、実際かなり楽しかったんです……大きな壁にぶつかるまでは。fisterfunk が shamrock portal とまったく会話せず、Snarfus に beep-boops も送ってくれなかったのです！ もちろん、それが何を意味するかはわかりますよね[3]――これで hoob-トンネル全体が gramelions で詰まってしまいました。受け入れられません。

もう少しで諦めるところでしたが、そのとき気づいたのです。backside Snarfus stagnator を backside shamrock Klingon troglodyte emulater に接続すれば大丈夫だと！ すると全部が beep-boops と ding-dongs し始め、ついにチュートリアルの本当の主題にたどり着けました。そして、望んだ方法でとても簡単なことができるようになったのです！ なかなかすごいでしょう[4]。

では、設定方法は次のとおりです。

  1. ターミナルで ajkl;gawgor;iqeg;iJLkqen. wl;R aw;oeiga 4648664 arjarwgj;llj;ja fadgfgajkljl; wlj;sdjk;lfas を入力
  2. 次に folder/hidden/deep/in/the/file/system/surprise!.file へ移動して、ファイルの内容をコピーします。もしそこになければ、library/library/library/llibrary/liiiiiibrarrrary/llllliiiiibrary/hidden/hidden/hiding/you can’t find me/hidden/nope/never/hahahahereiam.file にあるかもしれません
  3. もう一度ターミナルに戻ってファイルの内容を貼り付け、64A786AGR45JAR; rdja;jg [[]][[]][[]][[]]][()()()()()()()(){{}{}{}|{}{|}{}{|}{ ////////////////!! !!!! !! //// !!! agjlkargji;lwej;OI [ASRGASG[]ASGDASG[]EAEadgasg[]EAGE[edaga][]ahgr-0-0=-0-=0-=0=0-0=-0-=0=-0-=0=-0=-0!!! を入力
  4. Boop![5]
  5. Snarfus を開いて、今作成したファイルをアップロードします
  6. ただのお遊びとして、chronostatiomatrix の sham を解除したければ、—()()(]]asdg a=-do —cd go cd stay —sususudododo baby shark—][] を実行してもかまいません。任意です
  7. 完了！

どうなったか教えてください。この方法を GewGawGamma や ometer2.7 と一緒に使っている人がいるのかも気になります。」

脚注の説明

  1. 有名な会社らしいが、私は知らない
  2. まったく簡単ではない
  3. 何を意味するのかわからない
  4. すごいのはわかるが、理解はできなかった。それでもあなたにできたならよかった
  5. 最初の3ステップには、およそ7時間と193回の検索が必要になるだろう。でも Boop! にたどり着いたときの高揚感はすごい

まとめ

  • 「これはただ楽しみのために書いた文章です。知識を共有し、チュートリアルを書いてくれるすべての人に心から感謝します。」

関連記事

1件のコメント

 
GN⁺ 2025-09-23
Hacker Newsの意見

  • 最低限の知識しかない人に実際にドキュメントどおり試してもらい、横で黙って見守るやり方を強く勧めたい。このときはまったく助けず、ひたすら観察するだけでよい。その過程で、ユーザーがどこでつまずくのか、著者本人には当たり前すぎて見落としていた点や、抜けている設定など、さまざまな問題を発見できる。もしユーザーが特にストレスなく目的を達成できれば、そのドキュメントは合格だ。そうでなければ、失敗した箇所を一つ残らず記録し、それぞれ改善したうえで別の人で再テストする必要がある。FAANGのような大企業のドキュメントでもこの基準を満たしていないものを見たことがある。うちの組織が高い基準を設けていることに本当に感謝している。こういう形でドキュメントを作れば、繰り返しの会議、サポート依頼、ビデオ通話が減り、ユーザーが自力で問題を解決できるようになる

    • Appleのドキュメントではこうした問題がよく起きると感じている。文書中の定義が単に名前を言い換えただけで説明になっていないことが多く、もっと具体的に書いてほしい
    • 「話さず観察だけしろ」というルールは簡単そうに見えるが、実際には我慢できず説明したりヒントを出したりする人が多かった。中には自分でマウスを握ってしまう人までいた。こうした人間的な反応を避けるには、中立な進行役（モデレーター）を別に置き、著者や開発者は観察だけするのも役に立つ。ただし「ただ見守る」技術そのものを身につけることが重要で、さらに深めたいなら "think-aloud protocol（発話思考法）" を調べることを勧める
    • たいていの企業チームのオンボーディング文書は質がひどく、実際の業務負荷を事前に見せる窓口になっている。最近入った3つのチームは、文書がほとんど存在しないか古すぎて、必要なアクセス権やデプロイパイプラインの情報を得るために関係者を自分で探し回らなければならなかった。その過程で新しい文書を書いても、システムや権限が追加されるとすぐ古くなるという悪循環だった。必要な環境を2日で全部そろえてくれたチームが1つだけあり、その体験は最高だった。いまは新しいdevexチームで、ドキュメント環境そのものを改善しようと取り組んでいる
    • ひどいセットアップ文書を読みながらオンボーディングするのは、本当にストレスが10倍になる感覚だ。私はいつも、新入社員が経験した問題を最初の貢献としてすぐ修正するよう勧めてきた。新入社員には文脈が何もないので、最高のレビュアーになれる
    • うちの組織でも同じワークフローを使っている。経験の浅い人にドキュメントをたどってもらい、その後は全員が継続的に改善するよう促してきた。長年の経験者に生じる「盲点」を新入りがうまく見つけてくれるからだ。私の経験では、ユーザーの自信をどう保つかも非常に重要だという教訓を得た。だから「このシェルコマンドを実行してください」のような手順では、いくつかのセクションを折りたたんだ状態で提供している（例: 正常に実行された出力例、無視してよい警告、起こりうるエラー一覧と対処法、複雑なコマンドの説明など）。1つの手順に丸1ページ分の説明が付くこともあるが、オンボーディングではこうした詳細さが実際に非常に役立っている

  • ブログ記事のタイトルは「非開発者の私が、開発者のあなたが書いたチュートリアルを読む」だったが、HNのタイトルは「初心者開発者の私が...」に変えられていた。非開発者と初心者開発者はまったく別物だ。たとえば人事担当や完全な非専攻者には、社内用語や概念そのものがまったくなじみのない可能性がある。この場合、開発者が完全に的外れな説明を書いていたなら批判されて当然だ。一方で初心者開発者なら、難しくても新しい用語や概念を自分で調べられるし、時間がたてば新しく入ってきた初心者のために文書を更新することさえできる

    • 参考までに、投稿時のタイトルは「非開発者」だったが、途中で「初心者開発者」に変えられた。筆者は技術専門ではないブロガーで、ウェブサイトやCSSを扱うには複数の技術文書を参照する必要があったはずだ。サイト公開や非専門家向けドキュメント不足について議論するほうが適切だったかもしれないが、HNコミュニティが別の方向に議論を広げたのも悪くない
    • この区別は非常に重要だ。筆者のAnnieは自分で「コンテンツ／ドキュメント関連の仕事」をしており、CSSも趣味だと明かしているので、「非専門の趣味開発者」層に当たる。今後ますます大きくなる領域だと思う。初心者や非開発者を含むチュートリアルを書くなら、cd ~/.snarfus(フォルダがなければ作成) のような文言にも、ほんの一言補足を入れるだけで十分役立つ。私も昔Debianをインストールしたとき、そうした小さな説明に大いに助けられた
    • 私がプログラミングを学び始めたころ感銘を受けたサイトは "FromZero" だった。非開発者を対象に、IDEのインストールからコンソールを開くところまで段階的に説明してくれたし、なじみのない用語には「後で扱う予定なので今は気にしなくて大丈夫です」といった形で安心させてくれたので最高だった。もちろん、文書作成には多くの時間と労力がかかるので、ときには説明が一部しかなくても、まったくないよりは良いとも思う。初心者開発者向けの文書は、非開発者に向けるくらいの配慮で書くべきだと思う
    • 何でも極端にやさしく説明してくれないとゲートキーピングだと主張する人もいるが、自分がつらいと感じていても、前提知識なしで何でもすぐ理解できるわけではないという点を見落としていると思う
    • もし初心者開発者向けのチュートリアルであり、プロの開発者向けの記事でないなら、いちいち "Hoobijag" や "shamrock portal" のような概念まで全部説明してもらえると期待するのは変だ。結局、私たちも皆、最初は知らない用語をGoogleで調べながら覚えてきたのだから

  • ほとんどのチュートリアルは非開発者向けではなく、同僚開発者どうしの情報共有に近く、学術論文のように特定の知識集団に向けた文書と似た立ち位置にある。こうした形も悪くない。むしろ、昔の自分が記録しておいた文書を後から見返すのにも向いている。だからこそ初心者向けのコースや教材が別に存在する。もしチュートリアルが毎回3万字かけて背景説明から始めなければならないなら、誰も最後まで読まないだろう。逆に背景説明を増やしても、ある人にはなお不足に感じられるかもしれない

    • 息子（17歳）がプログラミングにとても興味を持っているので、最近 public/private/internal/static の概念に加えて再帰まで教えた。次にどんな反応をするか内心楽しみにしている
    • 「チュートリアルの大半は非開発者向けではない」という主張には同意しない。今回のチュートリアルの見出し自体が、非開発者を意図していることを明確にしている点をはっきりさせたい。オープンソースプロジェクトをインストールしようとして苦労し、ごく基本的なインストールガイドでさえ初心者がたどれるよう平易にすべきだという声は絶対に必要だ。些細な手順を省くだけで、不慣れな分野では何時間も失うことがある
    • むしろ、ドキュメントを誰にとっても親切に書くことを悪いとは思わない。良い文書は初心者だけでなく開発者にも役立つ。アクセシブルな文書がない理由は、単に少し余分な労力をかけたくないからだと思う。また、開発者向け文書は論文と違って、あまりに簡潔すぎたり、書き手が読み手を気にしていなかったりすることが問題だ。その結果、結局は専門家以外には役に立たない文書になってしまう。これは失敗だ
    • 初心者のために文脈を順を追って積み上げるタイプの文書が必要だという点には同意する。ただ最近は、DX（開発者体験）の改善が「簡単さ」ばかりを優先し、以前は有用だったログやエラーメッセージの検索性などを犠牲にして、結果として初心者だけを狙い、既存ユーザーには使いにくくなる傾向がある
    • 今日のチュートリアルは、実際には「自分がXプロジェクトに貢献した」という実績作りのための記事が多いように見える。むしろ筆者が3か月後にもう一度自分のチュートリアルをたどってみれば、抜けている内容がはっきり見えて大きな改善になるはずだ

  • 多くのテクニカルライターは「知識の呪い」を十分に認識していない。以前、WoW（World of Warcraft）のギルドを運営していたことがある。40人が同時に集まりダンジョンに入り、協力して複数のボスと戦うのだが、ごく小さなミス1つで全滅することもある。だから全員がTeamspeakに集まり、戦略を事前に十分説明していた。このとき最大の教訓は「自分が何を言っているか相手は知らないと仮定せよ」と、「一度言ったことも繰り返せ」だった。たいていの人は分からないことがあっても割り込んで質問しないので、常に「今自分はどんな用語を使っているか」「この概念を相手は知らないかもしれない」と自問しながら説明を添える習慣は非常に効果があった。こうしたコミュニケーション経験はテクニカルコミュニケーションにもそのまま当てはまり、「知識の呪い」を越えようとする努力を体に染み込ませれば、他人の理解を大きく高められる

    • 昔のレイドギルドで、18歳のギルドマスターが大人たちをさまざまな時間帯から集め、分配や戦略、日程までうまく調整しているのを見て、「この子は今すぐマネージャーとして就職すべきだ」と感じた
    • 40人レイドを運営した経験があれば、誰でもプロジェクトマネージャーとして最高級の能力を持つことになる。まさに「散り散りの猫の群れ」を無駄なくまとめる仕事だからだ

  • 多くのプロジェクトのホームページやGitHub READMEは、まるで「これを読む人はすでに全部知っている」という態度で書かれている。私がドキュメントを見るときは、「なぜこのツールが必要なのか」「何の問題を解決するのか」「似た他のツールとどう違うのか」「今でも継続して使われているのか」「長所短所を自分で判断できる材料まで与えてくれるのか」といった細やかさがもっとほしい。たった5分でも「どんな初心者でも何を疑問に思うだろう？」と考えて書いてくれるだけで、アクセシビリティは大きく上がる。何年もかけて作ったプロジェクトでも、「ユーザーが見つけたことにすら気づかないまま、面倒になって諦める状況」が繰り返されるのは本当にもったいないと思う。そして、文書の種類ごとの役割をよく理解することも重要だ。https://diataxis.fr/ は良い出発点だ

    • ROS（ロボットソフトウェア）の分野ではREADMEが本当に不足していて、いつもストレスを感じていた。プロジェクト名以外に手がかりがなく、用途の把握すら難しいことが非常に多い。オープンソースだけの問題ではなく、職場でも同じ経験があり、READMEに説明を足すのは自分だけのように感じる。昔のモノレポ時代のほうがむしろ幸せだった
    • 開発者が愛情と労力を込めて作ったツールだということは理解しているが、ドキュメントさえしっかりしていれば参入障壁はずっと下がるはずだ。しかも、スタックを構成する他のコンポーネントの文書まで難しいと、学習曲線は指数関数的に急になる
    • 以前のHNでは、何をするプロジェクトなのかすら書いていないものが投稿されたことさえあった

  • 文書作成で最も重要なのは「対象読者の知識レベル」を明確に定めることだ。基準線を高く設定しても低く設定しても構わないが、その基準から大きく外れると一部の読者は必ず不満を持つ。こういうとき、言い訳を選ぶこともできるし、解決策を求めることもできる。実際、今はAI、Google、書籍などでたいてい何でもすぐ調べられる。"Shoobababoo が何か" や "なぜ quagmire を使うのか" が気になるなら検索すればいい。もちろん、可能な限り外部情報なしで自己完結する文書が理想ではあるが、世の中が常にそこまで親切とは限らない

    • だからこそ、さまざまな設定ガイドが「まず exeファイルをダブルクリックして Next を押す」から始まる傾向のほうが問題だ。ガイドの基準線設定は本当に重要だ
    • 私は主に社内の機微なシステム向け文書を書くのだが、ときには文書の冒頭に「このガイドは x、y、z の使い方をすでに理解していることを前提とする。そうでないならこの作業をしてはいけない」と明記する。アクセス権も制限されているが、万一DRシナリオなどで不慣れな人が使う可能性もあるので、「この程度も理解できないなら絶対に手を出すな」という境界線を意図的に残すこともある

  • 私が長年メンタリングで強調してきた原則は、「知っていることは共有するのが最善」ということだ。何かを知っているなら必ず説明し、もし相手がすでに知っていたとしても確認になるだけだし、知らなければ大きな助けになる。時には冗長すぎるという不満も出るが、「これは新人や顧客、マネージャーが見るかもしれないので、その人たちのためだった」と言えばたいてい理解してもらえる。この原則は開発、レポーティング、人事管理などあらゆる領域に通じる

    • もちろん、すでに知っていることを説明されるのを極端に嫌う人もいる。S/N比が悪すぎると、かえってコミュニケーションそのものを妨げることもある
    • 息子にビリヤードを教える経験でも似たことを感じる。警戒心を捨ててチーム内でコツを惜しまず共有する文化は、成長に大きく役立つ。メンタリングでは答えを与えるより、質問を通じて自分で見つけられるよう導いたほうが、本人が気づいたときに本当の成長が起きる
    • 誰にでもいちいち教えることは、「mansplaining」だと誤解されたり、「何でも知っているふりをしている」と政治的に危険視されたりすることもある。会社では、互いに質問されたときだけ答えるほうが安全な場合もある

  • 最近GitlabからDigitalOcean Kubernetesへアプリをデプロイしてみたが、3〜4個のサードパーティツールを、それが何をするものか説明もないまま実装しなければならず、コマンドラインに入力する名前やパスも自分で調べて入れる必要があった。何が基準で何を合わせるべきかも説明がない。Dockerにはかなり慣れているのに、これらのツールの文書は、ないほうがましと思えるほど不親切だった

  • 私が本を書くのをやめてチュートリアルサイトを作った主な理由は、チュートリアルをより多くの人に届けるために、さまざまなインタラクティブな仕組み（<abbr> 要素など）を使えるからだ。それにもかかわらず、今のWebコンテンツがいまだに紙の本の機能にとどまっていることにもどかしさを感じる。クリック、ホバー、折りたたみ、動画、ユーザー反応など数多くの機能があるのに、相変わらず壁のように長いテキストばかりだ。OPですら、脚注をクリックするとページ最下部までスクロールする方式を使っていて、それはWebの潜在力を十分に生かしていないように感じる

    • ちょうど今ブログのアップグレードに挑戦しているところなので、こういう形の（インタラクティブでよくできたチュートリアルを出している）サイトを勧めてもらえるならありがたい

  • 実際のところ、チュートリアルの多くは非開発者向けでも開発者向けでもなく、「不要に長いテキスト」の末に結局重要な1〜2ステップを飛ばしているだけのことが多い。最大の原因は、他人に説明するつもりで文章を書くのが難しいことだと思う。自分の頭の中にしかない内容を文章として展開しなければ、読者には絶対に伝わらない。「チュートリアル」ではなく「クックブック」のように書いたほうが、実践では使いやすく、バージョンアップ後に役立たなくなるのも防ぎやすい

    • 皮肉なことに、最近のオンラインレシピ（クックブック）のほうが、非開発者ブログ以上にどうでもいい雑談だらけなことが多い