拡張機能のユーザー ドキュメントを作成する

どの拡張機能にも、その機能と使用方法をユーザーに知らせるためのドキュメントが必要です。

最低限必要なドキュメントは、次の 3 つのマークダウン ファイルのセットです。

• PREINSTALL.md
• POSTINSTALL.md
• CHANGELOG.md

さらに、以下のものを作成することも検討してください。

• 拡張機能の公開リポジトリの README ファイル。
• 独自のウェブサイト上で公開され、PREINSTALL.md にリンクされているチュートリアル、ガイド、リファレンス。

ベスト プラクティス、一般的なフレーズや構造については、公式の Firebase Extensions で利用できるファイルをご覧ください。

README の作成

拡張機能ディレクトリには、README を含めることができます。firebase ext:dev:init コマンドで README が自動的に生成されるわけではありません。

Firebase CLI では、extension.yaml ファイルと PREINSTALL.md ファイルから取得した内容を含む README ファイルを自動生成する次の便利なコマンドがサポートされています。

firebase ext:info ./path/to/extension --markdown > README.md

公式の Firebase Extensions のすべての README ファイルは、このコマンドを使用して作成されます。

インストール情報を追加する

README を作成または生成したら、そこにインストール情報を追加します。次のスニペットをテンプレートとして使用できます。

---

## 🧩 Install this extension

### Console

[![Install this extension in your Firebase project](https://www.gstatic.com/mobilesdk/210513_mobilesdk/install-extension.png "Install this extension in your Firebase project")][install-link]

[install-link]: https://console.firebase.google.com/project/_/extensions/install?ref=publisher_id/extension_name

### Firebase CLI

```bash
firebase ext:install publisher_id/extension_name --project=[your-project-id]
```

> Learn more about installing extensions in the Firebase Extensions documentation:
> [console](https://firebase.google.com/docs/extensions/install-extensions?platform=console),
> [CLI](https://firebase.google.com/docs/extensions/install-extensions?platform=cli)

---

PREINSTALL ファイルの作成

PREINSTALL ファイルには、「マーケティング」ページの一種である拡張機能の概要が記載されます。

このファイルの内容

• 拡張機能についてのまとめ
• データベースの設定や Google 以外のサービスへのアクセスなどの前提条件のリスト（例）
• インストールの事前準備とその手順に関する簡単な説明
• インストール後に必要な作業（例）に関する簡単な説明（詳細な手順は POSTINSTALL をご覧ください）
• 請求による影響の簡単な説明（定型文から始まる）

この内容が表示される場所

• 拡張機能のページの extensions.dev。
• 拡張機能のソースコード リポジトリ（拡張機能ディレクトリ内）
• 拡張機能の README の一部として（Firebase CLI の --markdown > README.md フラグを使用する場合）

PREINSTALL ファイルは拡張機能のパラメータ値にアクセスできないため、パラメータ参照が実際の値でレンダリングされることはありません。

ベスト プラクティス

• 可能であれば、PREINSTALL ファイルの内容全体を 1 ページ未満にまとめます
• エンドユーザーが拡張機能をインストールする前に必ず知っておくべき情報を詳細に提供します
• 詳細な手順は POSTINSTALL ファイルまたはその他の補助ファイルに記述します
• 拡張機能をサポートする他のツールやスクリプトを提供するかどうかを簡潔に説明します

Billing

This extension uses other Firebase or Google Cloud services which may have
  associated charges:

*   <list Google services / products that your extension uses>
*   <list Firebase services that your extension uses>
*   Cloud Secret Manager <if the extension uses secret params>
*   Cloud Functions

When you use Firebase Extensions, you're only charged for the underlying
resources that you use. A paid-tier billing plan is only required if the
extension uses a service that requires a paid-tier plan, for example calling to
a Google Cloud API or making outbound network requests to non-Google services.
All Firebase services offer a no-cost tier of usage.
[Learn more about Firebase billing.](https://firebase.google.com/pricing)

<Applicable info about billing implications for non-Google services, such as:>
Usage of this extension also requires you to have a <non-Google-service> account.
You are responsible for any associated costs with your usage of <non-Google-service>.

POSTINSTALL ファイルの作成

POSTINSTALL ファイルは、拡張機能のインストール後の手順について詳しく説明するページです。

このファイルの内容

• Firebase セキュリティ ルールの設定やクライアント側コードの追加など、インストール後の必須作業の詳細な手順（例）
• インストールされた拡張機能をすぐに試すための一般的な手順（「コンソールに移動して、これを行います」など）
• 拡張機能、特に HTTP リクエスト トリガー型拡張機能のトリガー方法に関する基本情報
• インストールされた拡張機能をモニタリングする方法の簡単な説明（定型文から始まる）

この内容が表示される場所

• ユーザーが拡張機能をインストールした後の Firebase コンソール（インストールされた拡張機能の詳細カード）

  • 実際のプロジェクトに拡張機能をインストールして、POSTINSTALL コンテンツの表示を確認してください。

• 拡張機能のソースコード リポジトリ（拡張機能ディレクトリ内）

POSTINSTALL ファイルは、拡張機能のパラメータ値と複数の関数関連の変数にアクセスできます。Firebase コンソールに POSTINSTALL の内容が表示されると、パラメータや変数の参照ではなく実際の値が表示されます。詳しくは、POSTINSTALL ファイルでパラメータと変数を参照する方法をご覧ください。

ベスト プラクティス

• POSTINSTALL ファイルの内容全体は簡潔でありながら、わかりやすいものにします。
• 見出しを使って内容を分類し、タスクやコンセプトを分割します
• 特定のワークフローやタスクの詳細な手順は、ウェブサイト（例）や、拡張機能リポジトリ内の補足のマークダウン ファイル（例）で公開することを検討してください。
• パラメータと関数関連の変数を参照して、ユーザーが構成した値を手順に沿って確認できるようにします

パラメータと変数の参照

インストール後、Firebase コンソールに拡張機能の POSTINSTALL ファイルの内容が表示されます。パラメータと関数関連の変数（下の表を参照）を POSTINSTALL ファイルで参照すると、その参照に対応する、インストール済みインスタンスの実際の値がコンソールに表示されます。

POSTINSTALL ファイル内の構成済みパラメータ値にアクセスするには、次の構文を使用します。${param:PARAMETER_NAME}

また、次の関数関連の変数をPOSTINSTALL ファイル内でのみ参照することもできます。Firebase はこの変数をサポートしているため、インストール後の作業をユーザーにより簡単に提供できます。この変数の値はインストール後まで使用できないため、POSTINSTALL ファイルでのみ使用できます。

この表の function-name は、extension.yaml 内の関数のリソース オブジェクトの name フィールドの値です。

Monitoring

As a best practice, you can
[monitor the activity](https://firebase.google.com/docs/extensions/manage-installed-extensions_community#monitor)
of your installed extension, including checks on its health, usage, and logs.

拡張機能をトリガーする方法の文書化

拡張機能のユーザー ドキュメントで、拡張機能をトリガーする方法をユーザーに説明する必要があります。説明は必要に応じて詳細に記述できますが、POSTINSTALL ファイルを作成するためのベスト プラクティスの記載を忘れないでください。説明については、下記から拡張機能に該当する項目をご覧ください。

CHANGELOG ファイルの作成

このファイルの内容

すべての拡張機能には、公開した各拡張機能の新しいバージョンに含まれる変更が記載された CHANGELOG.md ファイルが必要です。各バージョンをレベル 2 のヘッダー（##）に配置します。それ以外の場合は、任意の Markdown 形式を使用できます。

次の例は、公式の拡張機能の 1 つからの抜粋です。

## Version 0.1.3

feature - Support deletion of directories (issue #148).

## Version 0.1.2

feature - Add a new param for recursively deleting subcollections in Cloud
Firestore (issue #14).

fixed - Fixed "cold start" errors experienced when the extension runs after a
period of inactivity (issue #48).

## Version 0.1.1

Initial release of the _Delete User Data_ extension.

この内容が表示される場所

• Firebase コンソールと CLI で、ユーザーが拡張機能の新しいバージョンにアップグレードしたとき。Firebase コンソールと CLI には、ユーザーがアップグレードを完了した場合に有効になる変更のみが表示されます。
• 拡張機能のソースコード リポジトリ（拡張機能のディレクトリ内）