■ 1. 公式ドキュメントにおける例の不足
- 例の必要性: ドキュメントを検索する際、95%の場合は単一の例で十分であるが、95%の場合は公式ソースで例を見つけることができない
- ターゲット層の問題: デフォルトで正式な技術ドキュメントはそのエコシステムに深く没頭している人をターゲットにしているように見える
- 開発者の現実: 多くの開発者は日々頭の中で多くの「世界」をやりくりしなければならず、プロジェクト、言語、フレームワーク間を移動する際にコンテキストを復元し何が起こっているのかを理解するためにかなりの精神的エネルギーを必要とする
■ 2. Python 3ドキュメントの例
- 複雑な説明: Python 3のドキュメントでmax関数の説明として「max(iterable, /, *, key=None) Return the largest item in an iterable or the largest of two or more arguments」と5つの短い段落が続く
- 必要な前提知識: これを理解するためには関数定義における*の意味、/の意味、位置のみのパラメータセパレータとは何か、イテラブルとは何か、キーワード専用引数とは何か、keyが通常何を意味するかなど、Pythonについてかなり知っている必要がある
- テキストの読解: どのような値を渡すことができ、実際に関数をどのように呼び出すかを理解するためにテキストを読む必要がある
- 詳細の重要性: これらは簡潔さのために省略できない重要な詳細である
■ 3. 効果的な例の提示
- 実用的なケース: 多くの開発者がそのページを見たのは単にカスタムソート関数を渡す方法を素早く見つける必要があったからである
- 具体的な例: 以下のような例が迅速に役立つ
- max(4, 6)は6を返す
- max([1, 2, 3])は3を返す
- max(['x', 'y', 'abc'], key=len)は'abc'を返す
- max([])はValueErrorを発生させる
- max([], default=5)は5を返す
- シンプルさ: このような例は理解しやすい
■ 4. ClojureDocsの成功例
- コミュニティベースのプロジェクト: Clojure界で人気のあるコミュニティベースのプロジェクトがclojuredocs.orgで、人々が組み込み関数の例を投稿するサイトである
- 実用性: 日常のコーディングにおいて素晴らしく不可欠であり、into、spit、mapなどのページが良い例である
- 関連機能の包含: 例にはしばしば関連する関数が含まれており、質問されている関数だけでなく実世界での有用性と実用性を高めている
■ 5. ドキュメンテーションの課題
- 4種類の区別の欠如: 主要なソフトウェアプロジェクトでさえ4種類の異なるドキュメンテーションを提供することはまれである
- クリックへの躊躇: 「Documentation」リンクをクリックすることに躊躇することが多く、それは簡潔で読みにくく自動生成されたAPIリファレンスである可能性が高い
- チュートリアルの選択: ウォークスルーが必要だからではなく例が必要だからという理由でチュートリアルを探すことを選ぶことが多い