ハクソク

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

例が最良のドキュメントである

228日前原文(rakhim.exotext.com)

概要

公式ドキュメントは多くの場合、 実用的なコード例 が不足しがち 多くの開発者が 複数の技術領域 を同時に扱う現実 簡単なサンプル があれば理解が格段に速くなる ClojureDocsのような コミュニティ主導の例集 の有用性 APIリファレンスよりも 具体例やチュートリアル を求める傾向

公式ドキュメントの課題

  • 公式ドキュメントは 熟練者向け の記述が多い傾向
  • 基礎知識 や文法の前提が多く、初心者や他言語経験者には難解
  • 例えばPython 3のmax関数ドキュメントでは
    • /や*の意味、 位置専用・キーワード専用引数 の理解が必要
    • イテラブル やkey引数の使い方の知識が前提
    • 実際の 呼び出し例 が少なく、使い方が直感的にわかりづらい

簡単な例の重要性

  • 多くの開発者は 実装例を一目で知りたい ケースが大半
  • 例えば以下のような例があれば、理解が一気に進む
    • max(4, 6) # → 6
    • max([1, 2, 3]) # → 3
    • max(['x', 'y', 'abc'], key=len) # → 'abc'
    • max([]) # ValueError: max() arg is an empty sequence
    • max([], default=5) # → 5
  • 例があれば説明文を読む必要が減る ため、効率的な学習が可能

ClojureDocsのアプローチ

  • ClojureDocs はコミュニティが 実例を投稿 できる仕組み
  • intoやspit、mapなどのページで 現実的な使用例 を多数掲載
  • 関連関数の例も一緒に載せることで 実践的な理解 が深まる
  • 日々の開発で参考になる ドキュメントとして高評価

ドキュメント利用時の心理

  • 公式「Documentation」リンクは 自動生成のAPIリファレンス が多く、敬遠されがち
  • 具体的な例やチュートリアル を求めて検索する開発者が多い
  • チュートリアルを選ぶ理由は 一から学びたいからでなく、例が欲しいから の場合が多い

まとめと提案

  • 公式ドキュメントにも シンプルな実例 を必ず掲載する工夫が必要
  • コミュニティ参加型の例集 を併設することで、実用性向上
  • 複数言語・フレームワーク間を移動する開発者 への配慮が今後の鍵

Hackerたちの意見

コードの例は、ドキュメントの退化や劣化を防ぐためにユニットテストとして実行できるけど、人間の言葉ではできない方法だよね。

└

今はLLM（大規模言語モデル）があるから、APIドキュメントをチェックするようになるかもね。

例は初心者やたまに使うユーザーには最適だけど、経験豊富な開発者には普通のドキュメントが必要だよ。パラメータのリストが全部載ってるやつね。例えば、requestsのページ。GoogleでいつもQuickstart[0]みたいな例がいっぱいのページに飛ばされるけど、上級者には全然役に立たない！俺の限られた脳でも、「get」を呼び出してHTTP GETを発行するのは覚えてるよ。他にどんなオプションがあるの？タイムアウトはどうするの？content-typeはどうやって渡すの？raise_for_statusは204を無視するの？どちらにもメリットはあるけど、開発者がどちらか一つしか時間がないなら、ちゃんとしたドキュメントを選ぶかな。 [0] https://requests.readthedocs.io/en/latest/user/quickstart/

└

例は初心者だけじゃなくて、実はすごく価値があることが多いんだ。中には、5秒で1時間分のドキュメントを読んで実験するのと同じ理解を与えてくれるものもある。特にgitのドキュメントページなんかがそうだよね。でも、概念的にはすごくシンプルだけど、明確かつ簡潔に説明するのが難しい単一の関数にも当てはまる。開発者はどちらの時間もないか、両方の時間があるかだよね。一方の生産性の壁を突破したら、もう一方はほんの少しの追加努力で済む。そういう場合は、両方を提供するべきだと思う。例外的に自己説明的なものが少数あるけど、そういう場合は通常ドキュメントだけで十分だね。

└

同意するよ。良いドキュメントはプログラムの動作をほぼ完全に指定していて、例だけでそれを実現するのは実用的じゃないし、無理だと思う。

└

参照のようなドキュメントを通じて動作を理解するより、例を通じて理解する方が何倍も簡単だよ。人は物の名前をつけるのが下手で、それをドキュメント化するのも苦手だからね。今日も数時間かけて、あるパラメータが特定の値のときだけ動作することを理解するのに苦労したよ。コードを理解するには魔法が多すぎて、LLMが最新バージョンはそのパラメータをサポートしてないって間違って教えてくるし、ドキュメントも見つからない。結局、動くはずの小さな例を作って、問題を絞り込むためにいろいろ変えてみるのが一番効果的だった。要するに、例は多くのことを凝縮した形式で示していて、非常に高い忠実度を持ってるんだ（通常は実行可能なコード例だからね）。APIドキュメントみたいなものは、比較的広範囲をカバーしていて、維持するのにかかる手間も少ない。ちなみに、俺は明確で、はっきりしていて、ほとんど努力なしでわかるような動作に関してはライブラリを全く信用してない。READMEの最初にそのことが書いてあったり、その一つのことを示すセクションがあったり、型で定義されていることが大事だと思ってる。ステータスコード周りの動作は変わるだろうと考えて、呼び出しコードではできるだけ問題を軽減するようにしてるよ。

└

たまに使うユーザー それが俺が投稿で指摘してることだよね。>プロジェクトや言語、フレームワークを行き来する時、コンテキストを復元して何が起こっているのかを理解するのにかなりの精神的エネルギーが必要だよ。

└

ちゃんとしたドキュメントは、詳細を提供する必要があるよね。でも、例を一つか二つ最初に出すのは、ユーザーにとってサクッと概要を掴むのにいい方法だと思う。インタラクティブな例があればなお良し。Redisみたいに、使い方の例があるとさらにいいよね。リンクはここだよ：https://redis.io/docs/latest/commands/incr/

└

それは相反するものじゃないよ。例とちゃんとした技術的なドキュメント、両方あってもいいんだ。

└

不公平な例だけど、Googleのドキュメントは最悪だよ。役に立たない簡単すぎる例が一つあるだけのクイックスタートか、全く別のサイトに自動生成されたクラスリストがあるだけで、説明はどこにも見当たらない。結局、使い方を学ぶためにライブラリのソースコードを見に行くことが多いんだ。

Diátaxisフレームワーク[1]は、異なるタイプのドキュメントとそれを使うタイミングについて良い提案をしているよ。これらのタイプの中で「最良」のものはないし、それぞれ異なる目的に役立つんだ。 [1] https://diataxis.fr/

└

概念的にはdiataxisは素晴らしいと思う。でも、実装するのは簡単じゃないよね。プロジェクトごとに各コンポーネントの比率が異なるし、すべての形式を同じフォーマットで一つのウェブサイトにまとめるのは非常に非効率的だよ。比率はコミュニティの採用や専門知識のレベルによっても変わるし、もっと実行可能な形になればいいのに。ドキュメントは難しい問題だし、いつかもっと良い方法が見つかるといいな。それまでは、ドキュメントはそこにかけられた時間と専門知識の量に依存するけど、リソースの制約でそれが十分じゃないことが多いんだよね。

両方必要で、それを避ける方法はないよ。例はライブラリの使い方をすぐに理解させてくれるし、統合のための良い出発点を提供してくれる。すべてのパラメータや設定の詳細な説明があれば、もっと複雑な問題を解決できて、ツールの全機能を理解できる。どちらかのドキュメントが欠けていると、俺はすごく困る。唯一の例外は、非常にシンプルなライブラリで、例がすでに知っておくべきことを全部教えてくれる場合だね。

└

同意、例とリファレンスドキュメントは必要だよね。可能なら、REPL環境も追加したいな。例をすぐに修正してテストできる能力があれば、ドキュメントの欠点をかなりカバーできると思う。

同じように、Unixのmanページも例が必要だよね。ほとんどの場合、ツールの使い方を知っている人向けの詳細なリファレンスとして書かれているけど、それはそれで有効な使い方だよね。でも、それだと初めてツールを使う人には全然役に立たない。良いドキュメントには両方が必要だよ。

└

完全に同意だけど、tldrがあるからね。最近、tldrにはサブコマンド用の別ページもあるって知ったよ。

└

もうあるよ - tldr。manと一緒に使うといいよ。

└

多くのマニュアルページに例があるのは、いつも嬉しい驚きだよね。でも、もっと詳しく書いてくれたらいいのに。

└

cheat.shをチェックしてみて。これをスクリプトに入れてるんだ：curl cheat.sh/"$1"

こういうの、UnityやUnrealで作業してると本当にイライラする。時々、ドキュメントが全然役に立たないことがあるんだ。Unrealのノードを理解しようとすると、ドキュメントページにはノードの画像と、その名前をちょっと長く言い換えたものしか載ってないことが多い。まるでそれが何か助けになるかのように。£JOBでUnityを使ってるときも、関数の使い方をちゃんと知りたいだけなのに、短い例があればすごく助かるのに。全体的にはいいけど、価値のある情報が全然ないページもある。もしUnityのドキュメントに自分の追加を提出できるなら、絶対にやってると思う。

└

£JOB ちょっと待って、みんな$を$jobのために使ってるのはお金を稼ぐためで、変数名として使ってるんじゃないの？私の世界観が崩れそうだから、やめてよ。

└

Unrealのドキュメントが全然ないのは本当にイライラするし、時間の無駄だよ。彼らは「コードがドキュメントだ」って考え方を強く持ってるみたいだけど（私は同意しない）、ブループリントの「ノードのスクリーンショット」ドキュメントは本当にパロディを超えてるよ。

Perlについて何を言おうと、Perlのドキュメントは本当に役立つよ。ドキュメントの最初にSYNOPSISセクションがあって、一般的な使い方の例が載ってるのが標準なんだ。そこから議論やリファレンス、さらに他の例が続くことが多い。例えば： https://perldoc.perl.org/bigrat https://perldoc.perl.org/Archive::Tar プロジェクトのドキュメントを書くなら、Perlのスタイルを参考にしてみて。幸い、そのスタイル自体がしっかり文書化されてるよ： https://perldoc.perl.org/perldocstyle#Description-and-synops...

└

2000年代初頭にperlをたくさん書いてたけど、2014年に偶然また触れるまで全然やってなかった。そしたらすぐに戻ってきた。まるで昔の友達と話してるみたいだった。何だろう、数学的な純粋さや一貫性ではないけど、Larry Wallの言語学のバックグラウンドや彼の一般的な態度には、何か特別なものがあるんだよね。

ドキュメントに例が少ないことはよくあるけど、明確な概念説明が不足してるのはもっと広まってるのが残念だね。

Clojureの世界で人気のあるコミュニティベースのプロジェクトはclojuredocs.orgで、そこでは人々が組み込み関数の例を投稿してる。学校でPHPを学んでた時、ドキュメントページの例や議論がいつも一番役立ってたな。

このアドバイスは絶対に無視して！昔のPythonの良いところは、ライブラリのドキュメントを見れば、各関数の引数や返り値がはっきり書いてあったことなんだよね。今は多くのJavaScriptやPythonのライブラリのドキュメントを見ると、例ばっかり。急いで何かを作るにはいいけど、問題を直したりライブラリをちゃんと学ぶには全然役に立たないよ。例があるのはいいけど、それはあくまでおまけで、ドキュメントとは別物だと思う。