Creare la documentazione utente per l'estensione

Ogni estensione deve avere una documentazione che spieghi agli utenti cosa fa l'estensione e come utilizzarla.

La documentazione minima richiesta è questo insieme di tre file Markdown:

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

Inoltre, dovresti anche prendere in considerazione la produzione di:

• Un file README per il repository pubblico dell'estensione.
• Tutorial, guide e riferimenti più lunghi pubblicati sul tuo sito web e collegati nel file PREINSTALL.md.

Per scoprire alcune best practice e la struttura e le frasi comuni, ti consigliamo di esaminare i file disponibili con le estensioni Firebaseufficiali.

Creare un file README

La directory dell'estensione può contenere facoltativamente un file README. Tieni presente che il comando firebase ext:dev:init non lo genera automaticamente.

Tuttavia, Firebase CLI supporta il seguente comando di praticità per generare automaticamente un file README contenente i contenuti estratti dal tuo extension.yaml file e dal tuo file PREINSTALL.md:

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

Tutti i file README per le estensioni Firebase ufficiali vengono generati utilizzando questo comando.

Aggiungere informazioni sull'installazione

Dopo aver scritto o generato un file README, aggiungi le informazioni sull'installazione. Puoi utilizzare il seguente snippet come modello:

---

## 🧩 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)

---

Scrivere un file PREINSTALL

Il file PREINSTALL è la panoramica dell'estensione, un tipo di pagina "di marketing".

Quali contenuti sono presenti in questo file?

• Descrizione completa delle funzionalità dell'estensione
• Elenco dei prerequisiti, come la configurazione del database o l'accesso a un servizio non Google servizio (esempio)
• Breve descrizione di eventuali attività di preinstallazione e relative istruzioni
• Breve descrizione di eventuali attività post-installazione (esempio) (le istruzioni dettagliate sono riportate in POSTINSTALL)
• Breve descrizione di eventuali implicazioni di fatturazione (inizia con testo boilerplate)

Dove vengono visualizzati questi contenuti per l'utente?

Console Firebase">

Console Firebase">

• Nella pagina dell'estensione su extensions.dev.
• Nel repository del codice sorgente dell'estensione (all'interno della directory dell'estensione)
• Come parte del file README dell'estensione (se utilizzi il flag Firebase CLI --markdown > README.md)

I file PREINSTALL non possono accedere ai valori dei parametri dell'estensione, quindi non devi aspettarti che i riferimenti ai parametri vengano visualizzati con i valori effettivi.

Quali sono delle best practice da seguire?

• Se possibile, mantieni i contenuti completi del file PREINSTALL su una sola pagina,
• Fornisci il livello di dettaglio che un utente finale deve assolutamente conoscere prima di installare l'estensione
• Inserisci istruzioni dettagliate nel file POSTINSTALL o in altri file supplementari
• Menziona brevemente se fornisci altri strumenti o script per supportare l'estensione

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

Scrivere un file POSTINSTALL

Il file POSTINSTALL è la pagina di istruzioni dettagliate post-installazione dell'estensione.

Quali contenuti sono presenti in questo file?

• Istruzioni dettagliate per eventuali attività di post-installazione obbligatorie, come la configurazione delle regole di sicurezza Firebase o l'aggiunta di codice lato client (esempio)
• Istruzioni generiche su come provare immediatamente l'estensione installata (ad esempio, "vai alla console, poi fai questo")
• Informazioni di base su come attivare l'estensione, in particolare per le estensioni attivate da richieste HTTP
• Brevi indicazioni su come monitorare l'estensione installata (inizia con il testo boilerplate)

Dove vengono visualizzati questi contenuti per l'utente?

Console Firebase">

Console Firebase">

• Nella console Firebase dopo che un utente ha installato l'estensione (nella scheda dei dettagli dell'estensione installata )

  • Assicurati di esaminare la visualizzazione dei contenuti POSTINSTALL installando l'estensione in un progetto reale.

• Nel repository del codice sorgente dell'estensione (all'interno della directory dell'estensione)

I file POSTINSTALL possono accedere ai valori dei parametri e a diverse variabili correlate alle funzioni dell'estensione. Quando i contenuti POSTINSTALL vengono visualizzati in nella console Firebase, vengono visualizzati i valori effettivi anziché i riferimenti ai parametri o alle variabili. Di seguito sono riportate ulteriori informazioni su come fare riferimento a parametri e variabili nel file POSTINSTALL.

Quali sono delle best practice da seguire?

• Mantieni i contenuti completi del file POSTINSTALL concisi, ma descrittivi.
• Seziona i contenuti utilizzando le intestazioni per dividere attività o concetti distinti.
• Valuta la possibilità di pubblicare istruzioni dettagliate per un flusso di lavoro o un'attività specifici sul tuo sito web (esempio) o in file Markdown supplementari all'interno del repository dell'estensione (esempio).
• Fai riferimento a parametri e variabili correlate alle funzioni in modo che l'utente veda i valori configurati nel contesto delle istruzioni

Fare riferimento a parametri e variabili

Dopo l'installazione, la console Firebase visualizza i contenuti del file POSTINSTALL dell' estensione. Se fai riferimento a parametri e variabili correlate alle funzioni (vedi la tabella di seguito) nel file POSTINSTALL, la console popola questi riferimenti con i valori effettivi dell'istanza installata.

Accedi ai valori dei parametri configurati nel file POSTINSTALL utilizzando la seguente sintassi: ${param:PARAMETER_NAME}

Puoi anche fare riferimento alle seguenti variabili correlate alle funzioni solo nel file POSTINSTALL. Firebase supporta queste variabili per consentirti di fornire più facilmente indicazioni agli utenti dopo l'installazione. Sono disponibili solo per l'utilizzo nel file POSTINSTALL perché i valori di queste variabili non sono disponibili fino a dopo l'installazione.

In questa tabella, function-name è il valore del name campo nell'oggetto risorsa della funzione all'interno di 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.

Documentare come attivare un'estensione

Nella documentazione utente dell'estensione, devi fornire istruzioni agli utenti su come attivare l'estensione. Queste istruzioni possono essere dettagliate quanto ritieni necessario, ma tieni presente le best practice per la scrittura di un file.POSTINSTALL Per indicazioni su come fornire queste istruzioni, espandi la sezione seguente che si applica alla tua estensione.

Scrivere un file CHANGELOG

Quali contenuti sono presenti in questo file?

Ogni estensione deve avere un file CHANGELOG.md che documenti le modifiche incluse in ogni nuova versione dell'estensione che pubblichi. Inserisci ogni versione sotto un'intestazione di livello 2 (##); in caso contrario, puoi utilizzare qualsiasi formattazione Markdown.

Il seguente esempio è un estratto di una delle estensioni ufficiali:

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

Dove vengono visualizzati questi contenuti per l'utente?

• Nella console e in CLI Firebase, quando gli utenti eseguono l'upgrade alle nuove versioni dell'estensione. La console Firebase e Firebase CLI mostrano solo le modifiche che avrebbero effetto se l'utente completasse l'upgrade.
• Nel repository del codice sorgente dell'estensione (all'interno della directory dell'estensione).