ハクソク

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

初心者の私が、あなたが私のために書いたチュートリアルをどのように読んだか

2025年9月22日原文(anniemueller.com)

概要

  • 開発者が Snarfus や Hoobijag などのツール・言語経験を紹介
  • Snarfus を使ったチュートリアルの導入と経緯説明
  • 技術的な課題と 独自の解決策 を共有
  • 実際のセットアップ手順を 端的に解説
  • コミュニティへの感謝 とユーモアを交えた締めくくり

開発者のバックグラウンドと経験

  • Hoobijag や jabbernocks、 ABCDE++++ での開発経験
  • ABCDE+/^+ は絶対に使わないというこだわり
  • Shoobababoo や時折 kleptomitrons も利用
  • Company1 での Shoobaboo 関連業務経験
  • Snarfus との出会いと興味の発展

Snarfusチュートリアルの導入と発見

  • 最初は Very Simple Thing2 でSnarfusを使い始める
  • chromus の複雑さにもかかわらず多用途性を実感
  • argyling the pintafore with the quagmire という独自アプローチ
  • hoobastank を使わない選択
  • 新しい方法が意外とうまくいき、楽しさを感じる

技術的課題と解決策

  • fisterfunk が shamrock portal や Snarfus と通信しない問題発生
  • hoob-tunnel が gramelions で詰まるトラブル
  • 諦めかけたが、 Snarfus stagnator と shamrock Klingon troglodyte emulater の接続で解決
  • すべてが正常に動作し、最終的な目的を達成

Snarfusセットアップ手順

  • ターミナルで ajkl;gawgor;iqeg;iJLkqen などのコマンド入力
  • folder/hidden/deep/in/the/file/system/surprise!.file の内容コピー
    • ファイルが見つからなければ、さらに深いパスを探索
  • ターミナルでファイル内容を貼り付け、 64A786AGR45JAR などのコマンド実行
  • Snarfus を開き、作成したファイルをアップロード
  • オプションで chronostatiomatrix のデシャム操作も可能
  • これでセットアップ完了

コミュニティへの感謝とまとめ

  • GewGawGamma や ometer2.7 での応用例への興味
  • チュートリアル作者や知識共有者への感謝の気持ち
  • ユーモアを交えた温かい締めくくり
  • 複雑な手順でも達成感を楽しむ姿勢

Hackerたちの意見

ほとんどのチュートリアルは非開発者向けじゃなくて、エコシステム内の他の開発者向けなんだよね。一般向けのポップサイエンスの本や番組というより、学術論文みたいな感じ。これで全然いいし、むしろ素晴らしい！同じ仲間として、そういうチュートリアルからすごく助けられてる。時には、自分が何年も前に書いた忘れ去られたメモからもね。だから、コースや他の構造化された学習教材が存在するんだよ。初心者は、ゆっくりと積み上げられた文脈の中で育てられなきゃいけない。もしすべての記事が最初から始まらなきゃならなかったら、面白いことには決してたどり着けないよ。30,000語の前置きの後にやっと面白い部分にたどり着いた頃には、読者はもういなくなってるだろうし。次の読者は、30,000語じゃトピックの紹介としては足りないって文句を言うだろうね。40,000語が必要だって。

└

ほとんどのチュートリアルは非開発者向けじゃなくて、エコシステム内の他の開発者向けなんだよね。今のチュートリアルって、他の開発者を助けるためというより、自分の履歴書や四半期の評価に「公に貢献した」って書くためのものって感じだよね。もし元の著者が3ヶ月後に戻ってきて、自分の指示を再確認してくれたらもっと良くなると思う。そうすれば、彼らが見落としてた小さなことに気づくはずだから。

└

「ほとんどのチュートリアルは非開発者向けじゃない」ってコメントで何度も繰り返されてるけど、見出し自体がこのチュートリアルも非開発者向けだと言ってるんだよね。著者が単にインストールしたかっただけのオープンソースのGithubプロジェクトみたいなもので、コードに手を加えようとしているわけじゃない。基本的には、インストールのREADMEについて皮肉を込めて文句を言ってる感じで、もっと簡単にできるようにして、非開発者も簡単なステップを踏めるようにしてほしいってこと。これは、私が開発者であっても非常に同意できる不満だよ。でも、しばしば小さなステップが省かれてしまって、慣れていない分野でそれが起こると、たくさんの時間を無駄にすることになるんだ。

└

初心者は、ゆっくりと積み上げられた文脈の中で育てられなきゃいけない。うちの息子は17歳で、プログラミングにすごく興味があるんだ。先日、パブリック、プライベート、内部、そしてスタティックについて説明しなきゃいけなかった。で、冗談で「明日、先生に再帰について聞いてみなよ」って言ったんだ。今週末は母親と一緒にいるけど、その後どうなったか聞くのが楽しみだよ。

└

初心者は、徐々に積み上げられる多くの文脈で育てられる必要がある。そう思うし、そういう人たち向けに書く時は、詳細に書いて、彼らがついていけるようなストーリーを作るようにしてる。でも、DXをスムーズにしようとする試みには不満がある。多くのプロジェクトがやってるけど、結局は絶対的な初心者にしか役立たないものになってる。ログが簡単にアクセスできなかったり、欠けていたりする。エラーを見つけるために切り貼りしたりgrepしたりするのも簡単じゃない。要するに、人々が物事を理解するために使ってきたツールやテクニックが、DXを良くする名目で貧弱な代替品に置き換えられている。これは良い傾向だとは思えない。

過去数十年にわたって指導してきた人たちに教えようとしてきたことの一つは、「共有することは、仮定することよりも良い」という原則だよ。何かを知っているなら、それを他の人と共有しよう。彼らが何かを知っているだろうと仮定しないで。もし彼らが知っていて、あなたが教えたら、それはただ彼らが既に知っていることを確認しただけ。もし彼らが知らなかったら、あなたは彼らを大いに助けて、物事をもっとアクセスしやすくしている。時々、人々は「長すぎる」とか「必要ない詳細を追加してる」と文句を言うけど、その場合は「これは[ジュニア|マネージャー|顧客]が見るかもしれないから」と言えばいい。人々は、説明が他の人のためだと褒められるのは気にしないよ。これは開発だけじゃなくて、投資報告や人材管理、納品管理にも当てはまる。

└

もし彼らが知っていて、あなたが教えたら、それはただ彼らが既に知っていることを確認しただけ。必ずしもそうとは限らないよ。これだと「マンプレイニング」って非難されるリスクがあるし、最近ではその定義も広がってる。さらに、あなたが「知ったかぶり」と思われるリスクもある。オフィスの人間関係に関しては、同僚にあなたに明確に説明してもらう負担をかける方がずっと安全だよ。

└

何かを既に知っていると言われると、驚くほど敵対的になる人に何人か出会ったことがある。具体的な例は今思い出せないけど、自分も以前はそう感じたことがあると思う。共有することが、仮定することよりも良いと考えるのは、局所的な最適解だけを考えた場合だけど、信号対雑音比が悪すぎると、もっと選択的であれば存在しなかったコミュニケーションの障害に直面することになるよ。

└

過去数十年にわたって指導してきた人たちに教えようとしてきたことの一つは、「共有することは、仮定することよりも良い」という原則です。何かを知っているなら、他の人と共有しましょう。原則としては完全に同意するよ。息子と僕は競技でビリヤードをしているんだけど、上達するにつれて、ほとんど誰もヒントを教えてくれないんだ。すごく競争が激しいからね。僕は彼にそれ以上のことを教えようとしていて、みんなが成長を助け合う素晴らしいリーグチームがあるんだ。指導（ただの教えることではなく）では、彼らが探している答えにたどり着くための質問をするように導くのが好きなんだ。彼らの頭の中のつながりが光る瞬間は、本当に素晴らしいよ。

ほとんどの技術ライター（一般的なコミュニケーターも）は、知識の呪いを十分に理解していないんだ。これを思い出すのは、ティーンエイジャーの頃にWorld of WarCraftのギルドを運営していた時だね。週に3〜4回「レイド」を組織してた。世界中のギルドメンバー40人が同時にサインインして、ダンジョンの中でドラゴンや他のモンスターと戦うんだ。ゲームでこんなに楽しいことはなかったけど、同時に教育的でもあった。戦いはすごく難しくて、たくさんの調整や戦略が必要で、小さなミスでも全員が死んじゃうことがあったから。だから、レイドに参加する全員はTeamspeakサーバーにサインインしなきゃいけなかった。これは基本的に音声だけのZoomコールで、私と任命したオフィサーたちが指示を出したり戦略を決めたりするためのものだった。コミュニケーションの重要な教訓をすぐに学んだよ：最悪を想定すること。驚くことに（当時の私には）、あなたが言っていることを理解できない人は、理解できないと教えてくれないんだ。だから、私は二つのルールを守るようになった。1. 一度言う価値があるなら、繰り返す価値もある。人々は半分しか聞いていない、気が散っている、注意を払っていないと仮定しよう。2. 人々があなたの知識を知っているとは仮定しない。実際、話している間は「リスナーが知らないかもしれないことは何か？」と自問自答しながら説明する。これらのルールを守れば守るほど、レイドはうまくいった。でも、WoWをやめた後も、この二つのルールは役立ったよ。特に二つ目は、知識の呪いを克服するのに役立つ。知識を持っている人が他の人もその知識を共有していると誤って仮定する現象だから。コミュニケーションの際に知識の呪いを考えることは、しばらくすると自然になってくる。そして、知識の呪いを気にしない他のコミュニケーターを観察すると、それが明らかになる。彼らは誰も理解できないような難しい用語や略語を使って自信満々に話し始めて、リスナーの理解なんて全く気にしないんだ。

└

40人のWoWレイドを運営できる人は、ほぼ確実にトップクラスのプロジェクトマネージャーになるってずっと言ってる。あのレイドは、猫を追いかけるようなもんだよ。気が散った、接続問題を抱えたティーンエイジャーの猫たちをね。

最近のプロジェクトのホームページやGitHubのREADME.mdって、「これを読んでるってことは、もう何のためのものか分かってるよね」って感じのノリが多いよね。もっと共感を持ってドキュメントにアプローチしてほしいな。何のためにあるのか、どんな問題を解決するのか、他の競合ソリューション（XやYなど）と比べてどうなのか、今でもベストな解決策なのか、それとも他のツールが主流になってメンテナンスモードなのかを教えてほしい。自分でメリット・デメリットのマトリックスを作れるようにしてほしいし、専門家だと思わないでほしい。自分に「人々がどんな質問を持つ可能性があるか、たとえ何を聞くべきか分からなくても」と考える時間を5分でも持って、それを書き留めてほしい。何ヶ月も何年もかけて何かを作っておきながら、他の人がそれを見つけやすくしないことで自ら台無しにする人の気持ちが全く理解できない。ドキュメントの種類についての視点を持つのもすごく大事だよね。https://diataxis.fr/ は、より良いドキュメントを作りたい人にとっての素晴らしい出発点だよ。

Hacker Newsで議論の続きを見る