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

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

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

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

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

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

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

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

特にREADMEに関するこの問題は、ROS関連のロボティクスをやっている10年間、ずっとイライラさせられてきたよ。コードに入る前に、そのリポジトリが何をするのかの唯一の手がかりが名前の解釈だけっていうリポジトリが多すぎる。でも、これは普遍的なことだと思うし、君が言及しているように。オープンソースだけじゃなくて、仕事でもそう感じる。自分の会社でREADMEを編集してリポジトリの目的や関連するリポジトリを説明するPRを出すのは自分だけのような気がする。（昔はモノレポがいくつかあってもっと幸せだったけど、今は小さなプロジェクトごとに未文書のリポジトリができるのがトレンドになってしまった。）

この気持ちに共感するよ。開発者が自分の時間で、愛情を込めてやっていることは完全に理解しているけど、それが参入障壁を下げるのに本当に役立つと思う。ツールが便利なスタックの一部として使われることが多いとき、他のコンポーネントのドキュメントも解読が難しいことがあるから、理解するのが何倍も難しくなるんだよね。

どんなドキュメントにもターゲットオーディエンスがあるよね。あなたのテストは、ターゲットオーディエンスが完全な初心者である場合にのみ非常に価値がある。もちろん、ターゲットを特定しても良いドキュメントを書くのは非常に難しいけど、全くそのテーマに無知な人にドキュメントをレビューしてもらうのは、量子物理学の博士論文をレビューするのと同じくらい無意味だよ。全く意味がない（信じて）。ドキュメントを書くのは難しい。まずは「誰のためにこれを書いているのか？」から始めよう。追記：OPの「専門知識が少ない」という部分を「完全な初心者」と誤解していたかもしれない。これは全く異なることだね。

これが私たちのドキュメント作成の流れでもあるよ。まず書いて、それからシステムにあまり詳しくない人に実行してもらう。みんなにドキュメントを改善するように促すのも大事だね。5年もシステムを使っていると、自分では気づかない盲点が出てくるから、経験の浅い人が指摘してくれることがある。そこで学んだ教訓は、ユーザーの自信を管理することが大切だってこと。だから、「このシェルコマンドを実行して」って指示する時は、デフォルトで折りたたまれたセクションをいくつかつけるようにしてる。成功した実行がどう見えるか、特に「無視できる警告」が含まれている場合はどうか、エラーが発生する可能性は？それは致命的なのか、すぐに修正できるのか？ちょっと複雑なシェルのことは、何がどうなっているかの説明もつけることが多い。そうなると、ランブックの一つのステップにドキュメントが1ページ分あることもあるけど、これが新しいチームメンバーのオンボーディングにすごく役立つことがわかった。今や、標準のランブックは私たちが使う普通のツールのクセやトラブルの良い紹介にもなってるんだ。

僕は中規模のソフトウェア会社でジュニアシステム管理者をやってる。ユーザー向けのワークフローをドキュメントにする時、ITに関係ない同僚2人にそれを通してもらって、彼らが気づいた小さなポイントをドキュメントに追加してもらってる。これで、他のユーザーがそのワークフローに参加する時の頭痛がかなり減ったよ。

以前、こういうのが得意な人と一緒に働いたことがある。彼はドキュメントを見ながら、指示通りにやって、問題が出たところを記録して、また最初からやり直すって感じだった。遅いように見えたけど、彼のドキュメントは素晴らしくて、彼が一回ずつやる方が、みんなが何度もやるよりも時間を節約できたと思う。

これは基本的に、スティーブ・クルッグの「考えさせないで」に書かれているユーザーテストのアプローチだね。アプリの使いやすさをテストするのにも使えるよ。

たくさんのドキュメントを書いてきたけど、数年にわたって見てきた大きな問題は、チームメンバー全体のスキルが落ちていくのを目の当たりにしたことだね。マネージャーからドキュメントを使うように言われて、それに従ったけど、必要なときにドキュメントの外で考えることができなくなってしまったみたい。Tier 1のサポート役にはドキュメントが役立ったと思うけど、ほとんどのチームにとってはドキュメントが足かせになって、役割を成長させてTier 2に上がることができなかったように見える。この問題をどう解決すればいいのか、ちょっと分からないな。

ジュニアにドキュメントを書き直させて、頭をひねりながらやらせて、理解できたらアップデートを出すのもアリだね。

自分が開発しているソリューションを実行するためのDockerイメージを常に提供するようにしてるよ。大体はそのDockerイメージが使われないことが多いけど、これは重要な練習なんだ。新しいシステムで自分のソリューションを実行することを強いられるから、結果的にドキュメントがより完全になるし、依存関係も簡単に確認できる形で記録されるんだ。

ただ見てて。これには自分に厳しくなる必要があって、人気を追い求めていることを理解しないといけない。ユーザーに人気があるのはいいけど、ユーザーが顧客じゃない場合もあるからね… > 自分はFAANGのドキュメントを使ったことがあるけど、上記の基準を満たすものには程遠いよ。… FAANGはその良い例だね。彼らのドキュメントやコードがひどいから、統合にかかる時間が誰も予想できないくらい長くなる。これが実際にはマネージャーが二回目の統合を考えるのをためらわせるんだ。つまり、「上記の基準を満たす」ことが必ずしも良いビジネスとは限らないし、そのことを忘れないことが大事だと思う。

特に、たまにしか使わない重要な技術のドキュメントを使うときは、忘れがちなんだよね。まだその知識が失われていないときに、書くときに見失いやすい重要なポイントだよ。

「私、初心者」と書いてあるね。HNの投稿者はおそらく長さのために編集したんだろう。

それは全てを変える。初心者の開発者が、他の開発者向けに作られた技術的な投稿が「What's Hoobijag/jabbernocks/ABCDE++++/Shoobababoo/シャムロックポータル」について説明してくれることを期待するのは無茶だよね。知らない言葉をググらなきゃいけないフェーズをみんな通ってきたから。

僕がティーンエイジャーの頃にプログラミングに興味を持つきっかけになったサイトは「FromZero」っていうもので、非開発者向けにC言語でプログラムを書く方法を説明してた。IDEのインストールからコンソールの開き方まで、各ステップを丁寧に説明していて、「Snarfusのことは心配しないで、後で説明するから」って言ってたのがすごく良かった。あのサイトのおかげで今のキャリアがあるんだ。とはいえ、ドキュメントを書くのは時間がかかるし、優先事項じゃないかもしれない。この場合、部分的なドキュメントが全くないよりはマシだと思う。でも、初心者の開発者を対象にするなら、彼らを非開発者として考えるべきだと思うよ、君が正しく説明したように。

こんにちは、今ちょうどブログをアップグレードしようとしてるんだけど、うまくやってるサイトを教えてもらえる？

読者に必要な知識やスキルの基準を設定することが大事だよ いろんなガイドが「制御システムシミュレーション」や「産業オートメーションのコンプライアンステストベンチ」みたいな設定をする時に、「exeをダブルクリックして次へ進む」から始まるのが多いよね。ガイドのユーザーに期待される知識の基準はめっちゃ重要だよ。