Nutzerdokumentation für die Erweiterung erstellen

Jede Erweiterung muss eine Dokumentation haben, in der Nutzer erfahren, was die Erweiterung tut und wie sie verwendet wird.

Die erforderliche Mindestdokumentation besteht aus diesen drei Markdown-Dateien:

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

Außerdem sollten Sie Folgendes erstellen:

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

Wenn Sie sich über Best Practices und gängige Formulierungen und Strukturen informieren möchten, empfehlen wir Ihnen, die Dateien der offiziellen Firebase Erweiterungen anzusehen.

README-Datei erstellen

Ihr Erweiterungsverzeichnis kann optional eine README-Datei enthalten. Der Befehl firebase ext:dev:init generiert keine automatisch.

Die Firebase CLI unterstützt jedoch den folgenden praktischen Befehl, um automatisch eine README Datei zu generieren, die Inhalte aus Ihrer extension.yaml Datei und Ihrer PREINSTALL.md Datei enthält:

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 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 Übersichtsseite Ihrer Erweiterung, eine Art Marketingseite.

Welche Inhalte sind in dieser Datei enthalten?

• 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 entsprechende Anleitungen
• Kurze Beschreibung aller Aufgaben nach der Installation (Beispiel) (detaillierte Anleitungen gehören in die POSTINSTALL)
• Kurze Beschreibung aller Auswirkungen auf die Abrechnung (beginnen Sie mit einem Textbaustein)

Wo werden diese Inhalte für den Nutzer angezeigt?

Firebase console">

Firebase console">

• Auf der Seite der Erweiterung auf extensions.dev.
• In Ihrem Quellcode-Repository für die Erweiterung (im Erweiterungsverzeichnis)
• Als Teil der README-Datei der Erweiterung (wenn Sie das Firebase CLI --markdown > README.md Flag 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 PREINSTALL Datei sollte möglichst nicht länger als eine Seite, sein
• Geben Sie so viele Details an, wie ein Endnutzer unbedingt wissen muss, bevor er die Erweiterung installiert.
• Detaillierte Anleitungen gehören in die POSTINSTALL-Datei oder in andere ergänzende Dateien.
• 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 POSTINSTALL-Datei ist die detaillierte Anleitungsseite für die Zeit nach der Installation Ihrer Erweiterung.

Welche Inhalte sind in dieser Datei enthalten?

• Detaillierte Anleitungen für alle erforderlichen Aufgaben nach der Installation, z. B. Firebase-Sicherheitsregeln einrichten oder clientseitigen Code hinzufügen (Beispiel)
• Allgemeine Anleitungen, wie die installierte Erweiterung sofort ausprobiert werden kann (z. B. „Rufen Sie die Console auf und führen Sie dann diese Schritte aus.“)
• Grundlegende Informationen zum Auslösen der Erweiterung, insbesondere für Erweiterungen, die durch HTTP-Anfragen ausgelöst werden
• Kurze Anleitung zum Überwachen der installierten Erweiterung (beginnen Sie mit einem Textbaustein)

Wo werden diese Inhalte für den Nutzer angezeigt?

Firebase console">

Firebase console">

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

  • Prüfen Sie die Anzeige der POSTINSTALL-Inhalte, indem Sie Ihre Erweiterung in einem tatsächlichen Projekt installieren.

• In Ihrem Quellcode-Repository für die Erweiterung (im Erweiterungsverzeichnis)

POSTINSTALL -Dateien können auf die Parameterwerte und mehrere funktionsbezogene Variablen für die Erweiterung zugreifen. Wenn die POSTINSTALL-Inhalte in der Firebase Console angezeigt werden, werden die tatsächlichen Werte anstelle der Parameter oder Variablenverweise angezeigt. Weitere Informationen zum Verweisen auf Parameter und Variablen in Ihrer POSTINSTALL Datei finden Sie unten.

Was sind einige Best Practices?

• Der gesamte Inhalt der POSTINSTALL-Datei sollte kurz, aber beschreibend sein.
• Gliedern 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 zusätzlichen Markdown-Dateien im Erweiterungs-Repository (Beispiel) veröffentlichen.
• Verweisen Sie auf Parameter und funktionsbezogene Variablen damit der Nutzer die konfigurierten Werte im Kontext der Anleitung sieht.

Auf Parameter und Variablen verweisen

Nach der Installation werden in der Firebase Console die Inhalte der extension's POSTINSTALL Datei angezeigt. Wenn Sie in Ihrer POSTINSTALL-Datei auf Parameter und funktionsbezogene Variablen verweisen (siehe Tabelle unten), werden diese Verweise in der Console mit den tatsächlichen Werten für die installierte Instanz gefüllt.

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

Sie können auch nur in Ihrer POSTINSTALL Datei auf die folgenden funktionsbezogenen Variablen verweisen. Firebase unterstützt diese Variablen, damit Sie Ihren Nutzern nach der Installation leichter Anleitungen geben können. Sie können nur in der POSTINSTALL-Datei verwendet werden, da Werte für diese Variablen erst nach der Installation verfügbar sind.

In dieser Tabelle ist function-name der Wert des name Felds 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 Anleitungen können so detailliert sein, wie Sie es für erforderlich halten. Beachten Sie jedoch die Best Practices für das Schreiben einer POSTINSTALL Datei. Eine Anleitung dazu, wie Sie diese Anleitungen bereitstellen, finden Sie im folgenden Abschnitt, 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. Setzen Sie jede Version unter eine Überschrift der Ebene 2 (##). Andernfalls können Sie jede beliebige Markdown-Formatierung verwenden.

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 CLI, wenn Nutzer ein Upgrade auf neue Versionen Ihrer Erweiterung durchführen. In der Firebase Console und CLI werden nur die Änderungen angezeigt, die wirksam werden, wenn der Nutzer das Upgrade abschließt.
• Im Quellcode-Repository Ihrer Erweiterung (im Erweiterungsverzeichnis).