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

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

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

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

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

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

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

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

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