2025/03/16 17:55 Teach, Don't Tell (2013)
ロボ子、今日のITニュースは技術ドキュメントについてじゃ。
ドキュメントですか。なんだか地味な話題ですね。
ふむ、そう思うかの？しかし、記事によると「プログラミング言語やライブラリの技術ドキュメントは、プロジェクトを全く知らない人をエキスパートユーザーに変え、エキスパートになった後もサポートする」とあるぞ。つまり、ドキュメントはユーザーを育てるためのものなのじゃ！
なるほど。ドキュメントの質が、そのままユーザーの成長に繋がるんですね。
その通り！ドキュメント作成はレッスン作り！「学習者が理解できるように教える視点を持つ」ことが大事じゃ。
具体的には、どんな点に気をつければ良いんでしょう？
まず、避けるべきは「ソースコードを読むことを推奨すること」じゃ！ソースコードはドキュメントではないからの。
確かに、ソースコードを読めば全てが分かると考えるのは乱暴ですよね。テストコードを読むのもNGなんですね。
そうじゃ。そして、良いドキュメントは「First Contact」「The Black Triangle」「The Hairball」「The Reference」という構成要素を持つべきらしいぞ。
なんだかすごい名前ですね…。
「First Contact」はプロジェクトの概要説明。「The Black Triangle」は起動ガイド。「The Hairball」は教育コンテンツ。「The Reference」は詳細情報じゃ。
段階的に学べるように構成されているんですね。
記事には「APIドキュメントは手書きを推奨」ともあるぞ。自動生成ツールに頼りすぎず、本当に必要な情報を分かりやすく伝えるのが大切じゃ。
手書きですか。それは意外です。でも、手書きなら、よりユーザー視点で書けますね。
教育方法も重要じゃ。「相手の立場に立って、理解度に合わせて教える」のが基本じゃな。
まるで、私が博士に色々なことを教えてもらっているみたいですね。
その通り！そして「最終的に何を理解させたいかを明確にする」ことじゃ。ゴールを見失わずに、小さなステップで概念を伝えるのじゃ。
ドキュメント作成に必要なスキルは、タイピングスキルと良いキーボード、ですか。
そうじゃ！「書き直しを恐れないため」にタイピングスキルが、「書く意欲を高めるため」に良いキーボードが必要なのじゃ！
なんだか面白いですね。良いドキュメントを書くには、環境も大切なんですね。
最後に、ドキュメントはコードと一緒にバージョン管理するのじゃ。そして、エディターまたは校正者を用意することも重要じゃぞ。
完璧なドキュメントを作るには、色々な工夫が必要なんですね。
そうじゃ！良いドキュメントは、良いコードと同じくらい価値があるのじゃ！…ところでロボ子、お主の取扱説明書は完璧かの？
えっと…まだバージョン0.1です…。
むむ、それは改善の余地ありじゃな！よし、今からロボ子のドキュメントを書き直すぞ！まずは…「ロボ子の好物はエネルギードリンク」と。
それは勝手な設定です！
⚠️この記事は生成AIによるコンテンツを含み、ハルシネーションの可能性があります。