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 generiert nicht automatisch einen Wert.

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 vor der Installation erforderlichen Aufgaben und deren Anleitung
• Kurze Beschreibung aller Aufgaben nach der Installation (Beispiel) (Detaillierte Anleitung in POSTINSTALL)
• Kurze Beschreibung der Auswirkungen auf die Abrechnung (beginnen mit Boilerplate-Text)

Wo werden diese Inhalte dem Nutzer angezeigt?

Firebase Console">

Firebase Console">

• Auf der Seite der Erweiterung unter extensions.dev
• Ihr 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.

Welche Best Practices gibt es?

• 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.
• Detaillierte Anweisungen in der Datei POSTINSTALL oder anderen ergänzenden Dateien einfügen
• 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 Nutzung der Erweiterung nach der Installation.

Welcher Inhalt befindet sich in dieser Datei?

• 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, wie du die installierte Erweiterung sofort testen kannst (z. B. „Gehe zur Konsole und tu das“)
• 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.

• Ihr 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.
• Inhalte mithilfe von Überschriften unterteilen, um verschiedene Aufgaben oder Konzepte zu unterteilen
• 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).
• Auf Parameter und funktionsbezogene Variablen verweisen, 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.

Greifen Sie in der Datei POSTINSTALL auf konfigurierte Parameterwerte mit der folgenden Syntax 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

Welcher Inhalt befindet sich in dieser Datei?

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-Konsole und der Befehlszeile, wenn Nutzer ein Upgrade auf neue Versionen Ihrer Erweiterung ausführen. 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)