パッケージページの作成
このページにあるガイドラインは、pub.dev で優れたパッケージページを作成するのに役立ちます。具体的には、このページには、次のスクリーンショットで README (このドキュメント) としてマークされているコンテンツを提供する、より良いパッケージ README を作成するためのヒントが記載されています。
パッケージページの他の部分の詳細については、次のリンクに従ってください。
優れたREADMEを作成することは重要です
#pub.dev でパッケージを見つけたユーザーは、パッケージを試すかどうかを決定する際に README を素早くスキャンする可能性が高いです。優れた README は、読者の注意を引き、パッケージを試す価値があることを示します。
このページでは in_app_purchase パッケージの README を取り上げていますが、ご自身のパッケージはそれほど大きく詳細である必要はないかもしれません。パッケージがシンプルで UI が関連していない場合、README は yaml パッケージの README のようになるかもしれません。
優れたREADMEのための7つのヒント
#pub.dev でうまく機能する README を作成するための提案をいくつかご紹介します。
1. 短い説明を一番上に記載する
#ユーザー調査によると、パッケージユーザーは、パッケージの説明を数秒読んでから、README の残りを読むかどうかを決定します。したがって、パッケージが何をするのか、または達成するのかを、一目でわかるように簡潔に記述する必要があります。短く甘い説明を作成するために時間を費やし、ユーザーが意思決定できるように支援してください。
優れた説明の例をいくつかご紹介します。
虹を表示するための Flutter プラグイン。機械学習を使用して鳥の音を分類します。
プロジェクトのステータスや制約などの重要な情報も、一番近くに配置する必要があります。たとえば
iOS バージョン 10.3 未満では動作しません。
こちらは in_app_purchase パッケージページのスクリーンショットで、パッケージの簡単な説明と注意事項から始まります。
バッジ は、README の一番近く、短い説明の上または下に配置されることがよくあります。
2. ビジュアルコンテンツを含める
#パッケージページが視覚的なコンテンツのないテキストの壁になっている場合、ユーザーはそれを威圧的だと感じて読むのをやめるかもしれません。パッケージが UI をサポートしている場合、画像は特に重要ですが、重要な概念を説明するためにも役立ちます。どちらの場合でも、視覚的なコンテンツは、ユーザーがパッケージを使用することに自信を持つのに役立ちます。
静止画、アニメーション GIF、動画 (MOV または MP4 ファイルなど) のような視覚的なコンテンツは、ユーザーが見つけやすい README の最初の方に配置してください。
以下のスクリーンショットは、視覚的なコンテンツを追加することで in_app_purchase パッケージページが最初から情報豊かに見えるようになった様子を示しています。(変更前の画像は左側、変更後は右側です。)
5. リストを使って重要な情報を提示する
#リストは、README の重要な情報に注意を引くことができます。リストは次のような用途に使用できます。
通常、リストは上記のリストのように箇条書きになります。もう 1 つのオプションは、次のセクションのプラットフォームサポートの表のように、表を使用することです。
パッケージの主な機能
#まず、パッケージが何ができるかを明確にリストアップしてください。一部のユーザーは非常に特定の機能を探しているかもしれません。これらのユーザーがパッケージがニーズをサポートしているかどうかを見つけられるように支援してください。
次のスクリーンショットは、in_app_purchase README がパッケージの機能をどのように提示しているかを示しています。
次のスクリーンショットは、just_audio README から、パッケージの機能とプラットフォームサポートをリストアップした表を示しています。
パラメータ、属性、またはプロパティ
#参照用にパラメータ、属性、またはプロパティをリストアップすることを検討してください。(パッケージ README のコンテンツは、パッケージページだけでなく、API リファレンスドキュメントにも表示されることを忘れないでください。)
たとえば、url_launcher パッケージには、サポートされている URL スキームの表があります。
API リファレンスドキュメントの特定の関数またはクラスへのリンクも役立つ場合があります。async パッケージの例を参照してください。
特殊な要件
#パッケージに、すべてのパッケージで必要とされるもの以上の特定のセットアップが必要な場合は、README にセットアップ手順をリストアップしてください。
たとえば、google_maps_flutter パッケージの次のスクリーンショットは、Google Maps Platform の開始方法に関する手順を示しています。
パッケージの範囲外の機能
#ユーザーがパッケージが役立つかどうかを知るのに役立つように、ユーザーが期待する可能性のある機能が、パッケージではサポートされていないことをリストアップしてください。
範囲外の機能のリストアップを検討する可能性のある例をいくつかご紹介します。
- ボタンパッケージがテキストボタンのみに焦点を当てており、アイコンボタンではない場合は、README でそのことを明確にしてください。
- パッケージが Android の特定のバージョンのみをサポートしている場合は、README でその旨を記述してください。
目次
#ユーザーは、目次があるページやセクションをナビゲートするのが容易になります。README のセクションが非常に長い場合は、セクションの冒頭でサブセクションを明確にリストアップすることを検討してください。
たとえば、in_app_purchase README の「使用方法」セクションには多くの例があります。次の目次は、ユーザーがどのような例が存在するかを理解し、興味のあるコードに移動するのに役立ちます。
6. 使用例を含める
#パッケージが有望に見える場合、ユーザーはパッケージをテストしたいかもしれません。「開始方法」または「使用方法」セクションに、ユーザーが簡単に理解できる少なくとも 1 つのコードサンプルを含めてください。理想的には、プロジェクトにコピー＆ペーストできるものです。さらに多くの例を提供できれば、ユーザーがパッケージを理解するのに役立ちます。
すべてのユーザーが英語を話すわけではありませんが、全員が Dart を話すことを忘れないでください！優れたコードサンプルは非常に役立ちます。パッケージの example ディレクトリの下に、pub.dev が Examples タブを埋めるために使用できる、より完全な例をいくつか追加することを検討してください。詳細については、パッケージレイアウトの規則 の Examples を参照してください。
次のスクリーンショットは、in_app_purchase パッケージの README にある複数の例の 1 つを示しています。
7. Dartコードのフォーマットを使用する
#コード例を追加する際は、3 つのバッククォート (```) の代わりに、3 つのバッククォートと dart (```dart) を使用してください。次の例が示すように、dart を追加すると、pub.dev が Dart 構文ハイライトを使用するように指示されます。
``` のみでフォーマット | ```dart でフォーマット |
|---|---|
| dart |
8. 関連用語に言及する
#最近の UX 調査によると、多くのユーザーは、探している機能を見つけるために、ページ内検索機能 (Control+F または Command+F) を使用しています。したがって、README に重要な用語を記載して、ユーザーが見つけられるようにしてください。
たとえば、ユーザーは in_app_purchase パッケージがアプリ内サブスクリプションをサポートしているかどうかを知りたいかもしれません。キーワード subscription を検索するユーザーは、ページがその用語を使用していない場合、ページを離れる可能性があります。
人々が検索する可能性のあるすべての用語に言及した後、使用する用語に一貫性を持たせてください。必要に応じて、用語を明確に定義してください。
たとえば、in_app_purchase パッケージは、最初に underlying store を定義しています。
ページの残りの部分では、その用語が一貫して使用されています。
9. 次にどこへ行くべきかユーザーに伝える
#ユーザーがパッケージについてさらに知ることができるように支援してください。潜在的なユーザーに伝えるための提案をいくつかご紹介します。
- パッケージについてさらに学ぶ場所。Medium の記事や YouTube の動画へのリンクを掲載できます。
- パッケージの使用方法についてヘルプを得る場所。課題トラッカー、チャットルーム、またはメールアドレスなどが考えられます。
- パッケージで何をする予定か。ロードマップ (README または外部ページ) は、ユーザーが必要な機能が間もなく利用可能になるかどうかを知るのに役立ちます。
- パッケージにコードを寄付する方法。
次のスクリーンショットは、in_app_purchase README の潜在的な貢献者向けの情報の部分を示しています。
優れたREADMEの作成についてさらに学ぶ
#このドキュメントでは、優れた README のための 7 つのヒントを提案しました。開発者ドキュメントに関する一般的な推奨事項については、Google Developer Documentation Style Guide でさらに学ぶことができます。その他のヒントをいくつかご紹介します。
- 画像の代替テキストを提供する。
- 簡潔にする。「お願いします」とは言わない。
- 行の長さは 80 文字以下にする。
- コードを正しくフォーマットする (
dart formatのように)。
優れた README の実践についてさらに学ぶには、次のリソースを参照してください。
- README チェックリスト
- 読者がプロジェクトに自信を持つのに役立つ README を作成するためのチェックリスト。
- Awesome README
- 素晴らしい README のキュレーションされた注釈付きリスト。
- README を作成する
- README の紹介、テンプレート、および優れた README のための提案。
- GitHub プロジェクトの優れた README を作成する方法
- 優れた README の主要な要素とテンプレート。
このページおよびその他のページにある提案は、すべてのパッケージに当てはまるわけではありません。創造性を発揮してください！ユーザーの立場になり、読者が何を読みたいか、知りたいかを想像してください。読者が必要とする情報を提供できるのは、あなただけです。