パッケージページの作成
このページのガイドラインは、pub.dev で優れたパッケージページを作成するのに役立ちます。具体的には、このページには、次のスクリーンショットでREADME（このドキュメント）とマークされているコンテンツを提供する、より良いパッケージ README を作成するためのヒントがあります。
パッケージページの他の部分の詳細については、次のリンクをたどってください。
良いREADMEを書くことは重要です
#pub.dev でパッケージを見つけた人は、パッケージを試すかどうかを決定する際に、README をすばやくスキャンする可能性が高くなります。優れた README は、読者の注意を引き、パッケージを試す価値があることを示します。
このページでは、in_app_purchase パッケージの README を紹介していますが、あなたのパッケージはそれほど大きく詳細である必要はないかもしれません。パッケージがシンプルで関連する UI がない場合、README は yaml パッケージのものに似たものになる可能性があります。
良いREADMEのための7つのヒント
#pub.dev でうまく機能する README を作成するためのいくつかの提案を次に示します。
1. 上部に短い説明を記述する
#ユーザー調査によると、パッケージユーザーはパッケージの説明を読むのに数秒しか費やさず、README の残りの部分を読むかどうかを決定します。したがって、パッケージが何をするか、または一目で達成することを簡潔に説明する必要があります。時間をかけて短く簡潔な説明を作成し、ユーザーが意思決定を行うのを支援してください。
良い説明の例を次に示します。
虹を表示するためのFlutterプラグイン。機械学習を使用して、鳥の鳴き声を分類します。
プロジェクトのステータスや制約などの重要な情報も、上部に近くにある必要があります。例:
10.3 より下の iOS バージョンでは動作しません。
パッケージの簡単な説明と注意書きで始まる、in_app_purchase パッケージページのスクリーンショットを次に示します。
バッジは、短い説明の上または下に、README の上部近くにあることがよくあります。
2. ビジュアルコンテンツを含める
#パッケージページがビジュアルコンテンツのないテキストの壁の場合、ユーザーはそれが威圧的だと感じて読まなくなる可能性があります。画像は、パッケージが UI をサポートしている場合に特に重要ですが、重要な概念を説明するのにも役立ちます。いずれにしても、ビジュアルコンテンツは、ユーザーがパッケージの使用に自信を持つのに役立ちます。
静止画像、アニメーション GIF、動画 (MOV または MP4 ファイルなど) などのビジュアルコンテンツを、ユーザーがそれらを見る可能性が高い README の先頭近くに配置します。
以下のスクリーンショットは、ビジュアルコンテンツを追加することで、in_app_purchase パッケージページが一目で有益に見えるようになった様子を示しています。(前の画像は左側にあり、後は右側にあります。)
3. 重要な情報を提示するにはリストを使用する
#リストは、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 の「使用法」セクションには多くの例があります。次の目次は、どの例が存在するかをユーザーが理解し、関心のあるコードに移動するのに役立ちます。
4. 使用例を含める
#パッケージが有望に見える場合、ユーザーはパッケージをテストしたい場合があります。「はじめに」または「使用法」セクションを含め、ユーザーが簡単に理解できるコードサンプルが少なくとも 1 つあり、理想的には、プロジェクトにコピーアンドペーストできるコードサンプルを含めます。パッケージを理解するために、より詳細な例をさらに提供できると、さらに良いでしょう。
すべてのユーザーが英語を話すわけではありませんが、すべてのユーザーが Dart を話すことを忘れないでください！優れたコードサンプルは非常に役立ちます。パッケージの example ディレクトリの下に、pub.dev が 例タブに入力するために使用できる、より完全な例を追加することを検討してください。詳細については、例 ( パッケージレイアウトの慣例)を参照してください。
次のスクリーンショットは、in_app_purchase パッケージの README のいくつかの例の 1 つを示しています。
5. Dartコードの書式設定を使用する
#コード例を追加するときは、3 つのバッククォートと dart (```dart) を、3 つのバッククォート (```) の代わりに使用してください。次の例に示すように、dart を追加すると、pub.dev に Dart 構文の強調表示を使用するように指示されます。
```だけでフォーマット | ```dart でフォーマット |
|---|---|
| dart |
6. 関連用語を記述する
#最近の UX 調査では、多くのユーザーがページ内検索機能 (Control+F または Command+F) を使用して、探している機能を検索していることがわかりました。したがって、ユーザーがそれらを見つけることができるように、README で重要な用語を必ず記述してください。
たとえば、ユーザーは、in_app_purchase パッケージがアプリ内サブスクリプションをサポートしているかどうかを知りたい場合があります。サブスクリプションというキーワードを検索するユーザーは、ページでその用語が使用されていない場合、ページを放棄する可能性があります。
人々が検索する可能性のあるすべての用語を記述した後、使用する用語について一貫性を持たせてください。必要に応じて、用語を明確に定義します。
例えば、in_app_purchase パッケージは、冒頭で基盤となるストアを定義しています。
ページ全体で一貫してその用語を使用しています。
7. 次にどこへ行くかをユーザーに伝える
#ユーザーがパッケージについて詳しく知るのに役立てましょう。以下は、潜在的なユーザーに伝えるべきことの提案です。
- パッケージについて詳しく学ぶ場所。 Medium の記事や YouTube の動画へのリンクを張ることができます。
- パッケージの使用に関するヘルプを得る場所。 課題追跡システム、チャットルーム、またはメールアドレスなどが考えられます。
- パッケージで何をしようとしているのか。 ロードマップ（README または外部ページ）は、ユーザーが求めている機能が間もなく実装されるかどうかを知るのに役立ちます。
- パッケージへのコードの貢献方法。
次のスクリーンショットは、潜在的な貢献者向けの情報を含む in_app_purchase の README の一部を示しています。
優れた README 作成について詳しくはこちら
#このドキュメントでは、優れた README のための 7 つのヒントを提案しました。開発者向けドキュメントに関する一般的な推奨事項の詳細については、Google Developer Documentation Style Guide を参照してください。追加のヒントを以下に示します。
- 画像の代替テキストを提供してください。
- 簡潔にしてください。「お願いします」は使わないでください。
- 行の長さを 80 文字以下にしてください。
- コードを正しくフォーマットしてください (
dart formatでフォーマットされるように)。
優れた README の実践方法の詳細については、以下のリソースを参照してください。
- README チェックリスト
- 読者があなたのプロジェクトに自信を持てるような README を作成するためのチェックリスト。
- 素晴らしい README
- 優れた README の厳選された注釈付きリスト。
- README を作成する
- README の概要、テンプレート、および優れた README のための提案。
- GitHub プロジェクトのための優れた README の書き方
- 優れた README の主要な要素とテンプレート。
このページやその他のページにある提案がすべてのパッケージに当てはまるとは限りません。創造性を発揮してください！ユーザーの立場に立って、読者が何を読んだり知りたいと思っているかを想像してください。読者が必要とする情報を提供できるのはあなただけです。
特に明記されていない限り、このサイトのドキュメントは Dart 3.5.3 を反映しています。ページの最終更新日は 2024-05-06 です。 ソースを表示 または 問題を報告。