Nutzerdokumentation für die Erweiterung erstellen

Für jede Erweiterung muss eine Dokumentation vorhanden sein, in der Nutzer erfahren, was die Erweiterung macht und wie sie verwendet wird.

Die erforderliche Mindestdokumentation besteht aus diesen drei Markdown-Dateien:

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

Außerdem sollten Sie auch Folgendes in Betracht ziehen:

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

Wir empfehlen, sich die Dateien anzusehen, die mit den offiziellen Firebase-Erweiterungen verfügbar sind, um einige Best Practices sowie gängige Formulierungen und Strukturen kennenzulernen.

README-Datei erstellen

Ihr Erweiterungsverzeichnis kann optional eine README-Datei enthalten. Beachten Sie, dass der Befehl firebase ext:dev:init nicht automatisch eine für Sie generiert.

Die Firebase-CLI unterstützt jedoch den folgenden praktischen Befehl, um automatisch eine README-Datei mit Inhalten zu generieren, die aus Ihrer extension.yaml-Datei und Ihrer PREINSTALL.md-Datei stammen:

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

Nachdem Sie eine README-Datei geschrieben oder generiert haben, fügen Sie ihr 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 Datei PREINSTALL ist die Übersichtsseite 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 Nicht-Google-Dienst (Beispiel)
• Kurze Beschreibung aller Aufgaben vor der Installation und der entsprechenden Anleitung
• Kurze Beschreibung der Aufgaben nach der Installation (Beispiel) (detaillierte Anleitung in POSTINSTALL)
• Kurze Beschreibung der Abrechnungsauswirkungen (beginnen Sie mit Standardtext)

Wo werden diese Inhalte dem Nutzer angezeigt?

Firebase Console">

Firebase Console">

• Auf der Seite der Erweiterung auf extensions.dev.
• Das Quellcode-Repository für Ihre Erweiterung (im Erweiterungsverzeichnis)
• Als Teil der README-Datei der Erweiterung (wenn Sie das Flag --markdown > README.md der Firebase-CLI verwenden)

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

Was sind einige Best Practices?

• Der gesamte Inhalt der Datei PREINSTALL sollte auf einer Seite untergebracht werden, sofern möglich.
• Geben Sie den Detaillierungsgrad an, den ein Endnutzer unbedingt wissen muss, bevor er die Erweiterung installiert.
• Geben Sie detaillierte Anleitungen in der Datei POSTINSTALL oder anderen ergänzenden Dateien an.
• Erwähnen Sie kurz, ob Sie andere Tools oder Skripts 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 ist die detaillierte Anleitungsseite Ihrer Erweiterung nach der Installation.

Welche Inhalte sind in dieser Datei enthalten?

• Detaillierte Anleitung für alle erforderlichen Aufgaben nach der Installation, z. B. das Einrichten von Firebase-Sicherheitsregeln oder das Hinzufügen von clientseitigem Code (Beispiel)
• Allgemeine Anleitung dazu, wie die installierte Erweiterung sofort ausprobiert werden kann (z. B. „Gehen Sie zur Konsole und führen Sie dann diese Schritte aus“)
• Grundlegende Informationen dazu, wie die Erweiterung ausgelöst wird, insbesondere für durch HTTP-Anfragen ausgelöste Erweiterungen
• Kurze Anleitung zum Überwachen der installierten Erweiterung (beginnen Sie mit Standardtext)

Wo werden diese Inhalte dem Nutzer angezeigt?

Firebase Console">

Firebase Console">

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

  • Sehen Sie sich die Darstellung der POSTINSTALL-Inhalte an, indem Sie Ihre Erweiterung in einem tatsächlichen 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. Weitere Informationen zum Referenzieren von Parametern und Variablen in Ihrer POSTINSTALL-Datei

Was sind einige Best Practices?

• Fassen Sie sich bei der Beschreibung des Inhalts der Datei POSTINSTALL kurz, aber beschreiben Sie ihn dennoch ausführlich.
• Gliedern Sie den Inhalt mit Überschriften, um verschiedene Aufgaben oder Konzepte voneinander abzugrenzen.
• Sie sollten detaillierte Anleitungen für einen bestimmten Workflow oder eine bestimmte Aufgabe auf Ihrer Website (Beispiel) oder in zusätzlichen Markdown-Dateien im Erweiterungs-Repository (Beispiel) veröffentlichen.
• Verweisen Sie auf Parameter und funktionsbezogene Variablen, damit der Nutzer seine konfigurierten Werte im Kontext der Anleitung sieht.

Parameter und Variablen referenzieren

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 verweisen (siehe Tabelle unten), werden diese Verweise in der Konsole mit den tatsächlichen Werten für die installierte Instanz gefüllt.

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

Sie können auch die folgenden funktionsbezogenen Variablen nur in Ihrer POSTINSTALL-Datei referenzieren. Firebase unterstützt diese Variablen, damit Sie Ihren Nutzern nach der Installation leichter Anleitungen geben können. Sie können nur in der Datei POSTINSTALL verwendet werden, da 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 Ihren Nutzern erklären, wie sie die Erweiterung auslösen können. Diese Anleitung kann so detailliert sein, wie Sie es für nötig halten. Beachten Sie jedoch die Best Practices für das Erstellen einer POSTINSTALL-Datei. Wenn Sie wissen möchten, wie Sie diese Anleitung bereitstellen, maximieren Sie den Abschnitt unten, der auf Ihre Erweiterung zutrifft.

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, die Sie veröffentlichen. Setzen Sie jede Version unter einen Header der Ebene 2 (##). Ansonsten können Sie die Markdown-Formatierung verwenden, die Ihnen am besten gefällt.

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 dem Nutzer angezeigt?

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