Nutzerdokumentation für die Erweiterung erstellen

Jede Erweiterung muss eine Dokumentation enthalten, in der Nutzer darüber informiert werden, welche Funktionen die Erweiterung hat und wie sie verwendet wird.

Die Mindestanforderungen an die Dokumentation sind diese drei Markdown-Dateien:

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

Außerdem sollten Sie Folgendes produzieren:

• Eine README-Datei für das öffentliche Repository der Erweiterung.
• Längere Anleitungen, Leitfäden und Referenzmaterialien, die auf Ihrer eigenen Website veröffentlicht und in Ihrer PREINSTALL.md verlinkt sind.

Best Practices sowie gängige Formulierungen und Strukturen finden Sie in den Dateien mit den offiziellen Firebase-Erweiterungen.

README-Datei erstellen

Das Erweiterungsverzeichnis kann optional eine README-Datei enthalten. Der Befehl firebase ext:dev:init erstellt keine automatisch für Sie.

Die Firebase-Befehlszeile unterstützt jedoch den folgenden Befehl zum automatischen Generieren einer README-Datei mit Inhalten aus der extension.yaml- und der PREINSTALL.md-Datei:

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

Alle README-Dateien für die offiziellen Firebase-Erweiterungen werden mit diesem Befehl generiert.

Installationsinformationen hinzufügen

Fügen Sie dem README-Dokument nach dem Erstellen oder Generieren Installationsinformationen hinzu. Sie können das folgende Snippet als Vorlage verwenden:

---

## 🧩 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-Datei schreiben

Die PREINSTALL-Datei ist die Übersicht Ihrer Erweiterung, eine Art „Marketingseite“.

Welche Inhalte sind in dieser Datei enthalten?

• Eine umfassende Beschreibung der Funktionen Ihrer Erweiterung
• Liste der Voraussetzungen, z. B. Datenbankeinrichtung oder Zugriff auf einen Drittanbieterdienst (Beispiel)
• Eine kurze Beschreibung aller Aufgaben vor der Installation und deren Anleitung
• Kurze Beschreibung aller Aufgaben nach der Installation (Beispiel) (Detaillierte Anleitung in POSTINSTALL)
• Kurze Beschreibung der Auswirkungen auf die Abrechnung (mit Standardtext beginnen)

Wo werden diese Inhalte für den Nutzer angezeigt?

Firebase Console">

Firebase Console">

• Auf der Seite der Erweiterung unter extensions.dev
• Das Quellcode-Repository für Ihre Erweiterung (im Erweiterungsverzeichnis)
• Im README-Dokument der Erweiterung (wenn Sie das Flag Firebase --markdown > README.md in der Befehlszeile verwenden)

PREINSTALL-Dateien können nicht auf die Parameterwerte für die Erweiterung zugreifen. Daher sollten Parameterverweise nicht mit tatsächlichen Werten gerendert werden.

Was sind einige Best Practices?

• Begrenzen Sie den gesamten Inhalt der Datei PREINSTALL nach Möglichkeit auf weniger als eine Seite.
• Geben Sie die Details an, die ein Endnutzer unbedingt wissen muss, bevor er die Erweiterung installiert.
• Fügen Sie eine detaillierte Anleitung in die Datei POSTINSTALL oder andere ergänzende Dateien ein.
• Geben Sie kurz an, ob Sie andere Tools oder Scripts zur Unterstützung der Erweiterung bereitstellen.

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-Datei schreiben

Die Datei POSTINSTALL enthält eine detaillierte Anleitung für die Erweiterung nach der Installation.

Welche Inhalte sind in dieser Datei enthalten?

• Detaillierte Anleitungen für alle erforderlichen Aufgaben nach der Installation, z. B. zum Einrichten von Firebase-Sicherheitsregeln oder zum Hinzufügen von clientseitigem Code (Beispiel)
• Allgemeine Anleitung zum sofortigen Testen der installierten Erweiterung (z. B. „Gehen Sie zur Console und führen Sie dann Folgendes aus“)
• Allgemeine Informationen zum Auslösen der Erweiterung, insbesondere für HTTP-Anfrage-ausgelöste Erweiterungen
• Kurze Anleitung zum Überwachen der installierten Erweiterung (mit Standardtext beginnen)

Wo werden diese Inhalte für den Nutzer angezeigt?

Firebase Console">

Firebase Console">

• In der Firebase-Konsole, nachdem ein Nutzer Ihre Erweiterung installiert hat (auf der Detailkarte der installierten Erweiterung)

  • Prüfen Sie die Darstellung der POSTINSTALL-Inhalte, indem Sie Ihre Erweiterung in einem echten Projekt installieren.

• Das Quellcode-Repository für Ihre Erweiterung (im Erweiterungsverzeichnis)

POSTINSTALL-Dateien können auf die Parameterwerte und mehrere funktionsbezogene Variablen für die Erweiterung zugreifen. Wenn der POSTINSTALL-Inhalt in der Firebase-Konsole angezeigt wird, werden die tatsächlichen Werte anstelle der Parameter- oder Variablenreferenzen angezeigt. Unten finden Sie weitere Informationen dazu, wie Sie in Ihrer POSTINSTALL-Datei auf Parameter und Variablen verweisen.

Was sind einige Best Practices?

• Der gesamte Inhalt der POSTINSTALL-Datei sollte prägnant, aber aussagekräftig sein.
• Unterteilen Sie den Inhalt mit Überschriften, um verschiedene Aufgaben oder Konzepte zu trennen.
• Sie können detaillierte Anleitungen für einen bestimmten Workflow oder eine bestimmte Aufgabe auf Ihrer Website (Beispiel) oder in ergänzenden Markdown-Dateien im Erweiterungsverzeichnis veröffentlichen (Beispiel).
• Verweisen Sie auf Parameter und funktionsbezogene Variablen, damit der Nutzer die konfigurierten Werte im Kontext der Anleitung sieht.

Verweise auf Parameter und Variablen

Nach der Installation wird in der Firebase-Konsole der Inhalt der POSTINSTALL-Datei der Erweiterung angezeigt. Wenn Sie in Ihrer POSTINSTALL-Datei auf Parameter und funktionsbezogene Variablen (siehe Tabelle unten) verweisen, werden diese Verweise in der Konsole mit den tatsächlichen Werten für die installierte Instanz ausgefüllt.

Rufe mit der folgenden Syntax auf konfigurierte Parameterwerte in der Datei POSTINSTALL zu: ${param:PARAMETER_NAME}

Außerdem kannst du auf die folgenden funktionsbezogenen Variablen nur in deiner POSTINSTALL-Datei verweisen. Firebase unterstützt diese Variablen, damit Sie Ihren Nutzern nach der Installation leichter helfen können. Sie können nur in der Datei POSTINSTALL verwendet werden, da die Werte für diese Variablen erst nach der Installation verfügbar sind.

In dieser Tabelle ist function-name der Wert des Felds name im Ressourcenobjekt der Funktion in extension.yaml.

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.

Dokumentieren, wie eine Erweiterung ausgelöst wird

In der Nutzerdokumentation Ihrer Erweiterung müssen Sie Nutzern erklären, wie sie Ihre Erweiterung auslösen. Diese Anleitung kann so detailliert sein, wie Sie es für erforderlich halten. Beachten Sie jedoch die Best Practices für das Erstellen einer POSTINSTALL-Datei. Maximieren Sie den Abschnitt unten, der für Ihre Erweiterung gilt, um eine Anleitung dazu aufzurufen.

CHANGELOG-Datei schreiben

Welche Inhalte sind in dieser Datei enthalten?

Jede Erweiterung muss eine CHANGELOG.md-Datei haben, in der die Änderungen dokumentiert sind, die in jeder neuen Version Ihrer Erweiterung enthalten sind. Geben Sie jede Version unter einem Level-2-Header (##) an. Andernfalls können Sie die Markdown-Formatierung verwenden, die Sie für angebracht halten.

Das folgende Beispiel ist ein Auszug aus einer der offiziellen Erweiterungen:

## 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.

Wo werden diese Inhalte für den Nutzer angezeigt?

• In der Firebase Console und in der Befehlszeile, wenn Nutzer auf neue Versionen Ihrer Erweiterung umstellen. In der Firebase-Konsole und der Befehlszeile werden nur die Änderungen angezeigt, die wirksam werden, wenn der Nutzer das Upgrade durchführt.
• Das Quellcode-Repository Ihrer Erweiterung (im Erweiterungsverzeichnis)