Creare la documentazione utente per l'estensione

Ogni estensione deve avere una documentazione che insegni agli utenti cosa fa e come utilizzarla.

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

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

Inoltre, ti consigliamo di produrre:

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

Per conoscere alcune best practice e la formulazione e la struttura comuni, ti consigliamo di esaminare i file disponibili con le estensioni Firebase ufficiali.

Creazione di un file README

Se vuoi, la directory dell'estensione può contenere un file README. Tieni presente che il comando firebase ext:dev:init non ne genera uno automaticamente.

L'interfaccia a riga di comando Firebase supporta però il seguente comando pratico per generare automaticamente un file README contenente i contenuti estratti dal file extension.yaml e dal 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.

Aggiungi le informazioni di installazione

Dopo aver scritto o generato un file README, aggiungi le informazioni di 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)

---

Scrittura di un file PREINSTALL

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

Quali contenuti sono presenti in questo file?

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

Dove vengono mostrati questi contenuti all'utente?

Console Firebase">

Console Firebase">

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

I file PREINSTALL non possono accedere ai valori dei parametri per l'estensione, pertanto non dovresti aspettarti che i riferimenti ai parametri vengano visualizzati con i valori effettivi.

Quali sono alcune best practice?

• Se possibile, mantieni i contenuti completi del file PREINSTALL in meno di una 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>.

Scrittura di un file POSTINSTALL

Il file POSTINSTALL è la pagina dettagliata delle istruzioni post-installazione della tua estensione.

Quali contenuti sono presenti in questo file?

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

Dove vengono mostrati questi contenuti all'utente?

Console Firebase">

Console Firebase">

• Nella console Firebase dopo che un utente ha installato la tua estensione (nella scheda dettagliata dell'estensione installata)

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

• Il repository del codice sorgente per l'estensione (all'interno della directory dell'estensione)

I file POSTINSTALL possono accedere ai valori dei parametri e a diverse variabili correlate alle funzioni per l'estensione. Quando i contenuti di POSTINSTALL vengono visualizzati nella console Firebase, vengono visualizzati i valori effettivi anziché i riferimenti ai parametri o alle variabili. Scopri di più di seguito su come fare riferimento a parametri e variabili nel file POSTINSTALL.

Quali sono alcune best practice?

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

Fare riferimento a parametri e variabili

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

Accedi ai valori del parametro configurato nel file POSTINSTALL utilizzando la seguente sintassi: ${param:PARAMETER_NAME}

Puoi anche fare riferimento alle seguenti variabili relative alle funzioni solo nel POSTINSTALL. Firebase supporta queste variabili in modo che tu possa fornire più facilmente indicazioni agli utenti dopo l'installazione. Possono essere utilizzati solo 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 campo name nell'objetto della 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.

Documentazione su come attivare un'estensione

Nella documentazione per gli utenti dell'estensione, devi spiegare agli utenti come attivarla. 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 di seguito che si applica alla tua estensione.

Scrittura di 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 pubblicata. Inserisci ogni versione sotto un'intestazione di livello 2 (##); in caso contrario, puoi utilizzare la formattazione Markdown che preferisci.

L'esempio seguente è 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 mostrati questi contenuti all'utente?

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