ライブラリの作成者が有益なドキュメントを作成するためのベストプラクティス
ライブラリが提供するドキュメントは非常に重要です。 それは、ユーザーがあなたのライブラリを調査するか、プロジェクトに採用するか、困難に遭遇したときに使い続けるかを決定づけます。 今日の開発者は、言語、ライブラリ、フレームワーク、プラットフォームに関して前例のない選択肢を持っています。 したがって、ユーザーを引きつけ、情報を提供することが不可欠です。さもなければ、彼らは他の選択肢を追求するかもしれません。
ライブラリのごく初期のバージョンでは、ユーザーからのフィードバックは不足しているでしょう。 幸いにも、ドキュメントの作成と改善は、プロジェクトの品質を大幅に向上させるフィードバックループとして機能します。 そのため、ドキュメントの作成は決して負担と見なされるべきではなく、ライブラリを作成する際の優先順位の低いものに追いやられるべきではありません。
効果的なドキュメントは、ユーザーに情報を提供するだけでなく、ライブラリの開発と改善を促進します。 ドキュメントが開発プロセスを導くいくつかの重要な方法を以下に示します。
- ライブラリが何をするのか、誰がそれを使うことで利益を得るのか、そして代替アプローチと比較してどのような利点があるのかを、数段落で説明できるようにするべきです。これができない場合、プロジェクトの範囲と目標を再考してください。
- 潜在的なユーザーができるだけ早く使い始められる「Getting Started (はじめに)」ガイドを作成できるべきです。迅速さの基準は問題領域によって異なりますが、他のプラットフォームの類似ライブラリと比較することができます。このガイドは、常に信頼性の高い結果を生み出しながら、より簡単かつ迅速に進行するフィードバックループにユーザーを引き込むべきです。このガイドを作成することは、ユーザーの進行を妨げる可能性のある、複雑性の急激な増加（断崖絶壁）を特定するのに役立ちます。
- 関数をドキュメント化する行為は、入力の有効な範囲、スローされる可能性のある例外、作業量が増えるにつれてパフォーマンスがどのように低下するかなど、すべてのエッジケースを考慮するよう強制します。これはしばしば、関数シグネチャと基盤となる実装の改善につながります。
- ライブラリを初期化するために必要なコードが、タスクを達成するために必要なコードを常に上回る場合、設定オプションを再考してください。
- 標準オプションで基本的なタスクを実行する明確な例を作成できない場合、日常的な使用のためにAPIを最適化することを検討してください。
- 実際のデータソースやオンラインサービスを使用せずにライブラリをテストする方法を実証できない場合、ネットワーク（および一般に外部）にアクセスするコンポーネント用のテストダブルを提供することを検討してください。
ライブラリのドキュメントを早く提供すればするほど、実際のユーザーによるテストを早く行うことができます。 これらのテストからのフィードバックは、設計の改善に利用できます。
包括的なドキュメントを提供する
ユーザーが最小限の労力でライブラリを採用できるように、十分なドキュメントを提供する必要があります。 このドキュメントには以下が含まれるべきです。
- 「Getting Started (はじめに)」ガイド
- APIの詳細な説明
- 一般的なユースケースのより長い例（「レシピ」とも呼ばれます）
- ブログ、記事、ウェビナー、カンファレンス講演などのリソースへのリンク
「Getting Started (はじめに)」ガイドは、サポートされているビルドシステムとライブラリがどのように統合されるかをカバーすべきです。 最も一般的に使用されるエンティティの簡単な説明と、それらの使用方法の小さな例を含めるべきです。 ライブラリが外部と対話する各点で、環境を構成するために必要な手順と、これらの手順が正常に完了したことを確認する方法を指定してください。 手順が不要な場合は、明示的に記述してください。
可能であれば、サポートするライブラリの各バージョンごとに個別のドキュメントバージョンを提供してください。 これにより、ユーザーが古すぎる情報や新しすぎる情報を閲覧することを防ぎます。 これが不可能な場合は、APIの再設計された部分に関連するドキュメントのセクションを明確にマークしてください。
ユーザーのペルソナを作成する
対象読者を明確に理解せずにドキュメントを作成および評価することは困難です。 ドキュメントを読むユーザーのタイプごとに複数のペルソナ（personas）を定義することは役立ちます。
ユーザーが操作する必要がある既存のソフトウェアスタックなど、ユーザーの制約を考慮してください。 ドキュメントのレビュアーはこれらのペルソナを採用することで、その結論をより意味のあるものにすることができます。
ユーザーに関する具体的な情報が不足している場合は、悲観的であるのが最善です。 例えば、Kotlinの最新または最も高度な機能に関する専門知識を前提としないでください。 コード例は可能な限りシンプルに保ってください。
ペルソナは、時間、予算の制約、または機密保持契約のために実際のユーザーに相談できない場合に特に役立ちます。 時間が経つにつれて、ユーザーをよりよく理解するにつれて、ニーズに合わせてペルソナをより正確に調整してください。
可能な限り例でドキュメント化する
例によるドキュメント化は、ユーザーに基本的な概念を説明するための最も費用対効果の高い方法の一つです。 可能な限り、現在のトピックや概念を説明または実証するのに役立つ、シンプルで明確なコード例を提供してください。
KDoc ドキュメント形式では、ドキュメントコメントでMarkdown を使用したインラインマークアップを使用できます。 コメント内のインラインコードスニペットを使用して、APIの利用方法を紹介してください。 例として、コルーチンライブラリのテストディスパッチャーのソースコードとレンダリングされたドキュメントを参照してください。
このような例を提供することで、予期される入力、可能な出力、および失敗モードに関する冗長な説明を記述する必要を避けることができます。 ただし、各例のコンテキストは明確である必要があり、それが関連する状況も同様です。 単にコメントのないサンプルプログラムのフォルダを提供するだけでは、ドキュメントとは言えません。
APIを徹底的にドキュメント化する
すべてのサポートされているAPIエントリーポイントは、KDocを使用してドキュメント化されるべきです。
KotlinのドキュメントエンジンであるDokkaは、デフォルトでは公開宣言のみを出力に含めます。簡潔さのセクションで議論されているように、公開APIを最小限に抑え、ユーザーにアクセスさせたくない公開エントリーポイントを削除する必要があります。 可視性を制御してユーザーから隠せないAPIがある場合は、suppress ディレクティブを使用してドキュメントから省略してください。
エントリーポイントの説明は、その関数が何をするのかを明確で高レベルな説明から始めてください。 シグネチャを自然言語で単に再記述することは避けてください。
例えば、「String を受け取り、Connection を返す」と言うのではなく、おそらく「入力文字列で指定されたデータベースへの接続を試み、成功した場合は Connection を返し、それ以外の場合は ConnectionTimeoutException をスローする」のように記述してください。
各入力の予期される値と、異なる入力での動作を指定してください。 有効な値の範囲と、無効な値が提供された場合に何が起こるかを説明してください。 例えば、文字列入力がURLであるべき場合、その文字列が空、無効、サポートされていないプロトコルを使用している、または存在しない場所を参照している場合に何が起こるかを記述してください。
APIエントリーポイントがスローする可能性のあるすべての例外をドキュメント化してください。失敗条件については一般的な説明で議論し、例外セクションは詳細な情報のためにとっておいてください。これは可読性を高め、読者の集中を助けます。その代わりに、この情報を一般的な説明の中に自然に含めてください。可能な限り使用例を提供することも、ユーザーがAPIを正しく使用する方法を理解するのに役立ちます。
ドキュメントの明確さと効果を向上させるために、テクニカルライティングについて学ぶことをお勧めします。 Googleが提供するこのコース（パート1とパート2）などのリソースを検討してください。
ラムダパラメータをドキュメント化する
APIエントリーポイントがラムダを受け取る場合、ユーザーはライブラリがユーザーの代わりに実行する機能を提供しています。 これには、少なくとも2つの領域で追加のドキュメントが必要です。
まず、ラムダが例外をスローした場合に何が起こるかをドキュメント化してください。以下の質問に対処することを検討してください。
- これにより即座の失敗が発生するか、ラムダが繰り返し呼び出されるか、またはフォールバックの動作があるか？
- 呼び出し元の関数が終了する必要がある場合、ラムダからスローされた例外を再スローするか、異なる例外をスローするか？
- 例外が異なる場合、元の例外を含むか？
さらに、関数が inline として宣言されていない限り、並行性に関連する特別な動作をドキュメント化してください。 以下がカバーされていることを確認してください。
- ラムダは呼び出し元と同じスレッドで呼び出されるか？
- ラムダが呼び出し元と同じスレッドで呼び出されない場合、どのスレッド（またはスレッドプール）で呼び出されるか？
- ラムダの複数のコピーが並行して実行される可能性があるか？
- 他にどの作業がそのスレッドを使用している可能性があるか？
- ユーザーはライブラリが使用するスレッドを指定できるか？
- 複数のラムダが呼び出される場合、シーケンスに関してどのような保証が提供されるか？
ドキュメントで明示的なリンクを使用する
APIエントリーポイントがライブラリの他の機能から完全に独立していることは非常にまれです。 通常、呼び出しは特定のシーケンスで行われる必要があり、特定のタスクを実行するための複数のオプションがあり、関連するタスクを実行するエントリーポイントは同様の方法で使用されます。 例えば、format や parse のような関数は互いに対応しています。
これらの関係をドキュメントで明示的にするために、@seeタグまたは内部リンクを使用してください。 これは、読者が情報をチャンク化して、ライブラリのより統合されたメンタルマップを構築できるようにすることで、読者を助けます。
可能な限り自己完結型であること
入力を有効にするものが何かを説明する際、W3C、IEEE、Unicode Consortiumなどの関連する標準を参照したくなる誘惑に駆られます。 これらのリンクを提供することは役立ちますが、読者が空白文字のセットのような基本的な情報を発見するために外部の仕様を参照することを強制されるべきではありません。
可能な限り、ドキュメントは自己完結型であるべきです。 各APIエントリーポイントの典型的な使用方法をユーザーが理解するのに十分な情報を提供するべきです。 一般的な使用では発生しないエッジケースについては、ユーザーを外部ドキュメントに参照させることができます。
簡潔な英語を使用する
ドキュメントを作成する際には、シンプルで明確な英語を使用することが重要です。 これにより、母国語が英語ではない人を含む、世界中の読者にコンテンツがアクセス可能になります。 読者を混乱させる可能性のある複雑な単語、専門用語、ラテン語のフレーズ、または慣用表現の使用は避けてください。 その代わりに、率直な言葉と簡潔な文を使用してください。
簡潔な英語は、必要に応じてドキュメントを翻訳しやすくもします。 明確で曖昧さのないテキストは、誤解のリスクを減らし、全体的な可読性を向上させます。
次のステップ
まだの場合は、以下のページを確認してください。
- 精神的複雑性の最小化ページで、精神的複雑性を最小限に抑えるための戦略を探ります。
- 後方互換性ページで、後方互換性を維持する方法について学びます。