Membuat dokumentasi pengguna untuk ekstensi Anda

Setiap ekstensi harus memiliki dokumentasi yang menjelaskan kepada pengguna tentang fungsi ekstensi dan cara menggunakannya.

Dokumentasi minimum dan wajib adalah kumpulan tiga file markdown ini:

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

Selain itu, Anda juga harus mempertimbangkan untuk memproduksi:

• File README untuk repositori publik ekstensi.
• Tutorial, panduan, dan referensi yang lebih panjang yang dipublikasikan di situs Anda sendiri dan ditautkan di PREINSTALL.md.

Untuk mempelajari beberapa praktik terbaik serta frasa dan struktur umum, sebaiknya tinjau file yang disediakan bersama ekstensi Firebase resmi.

Membuat README

Direktori ekstensi Anda dapat berisi file README, jika diinginkan. Perhatikan bahwa perintah firebase ext:dev:init tidak otomatis membuat file ini untuk Anda.

Meskipun begitu, Firebase CLI mendukung perintah praktis berikut untuk otomatis membuat file README berisi konten yang diambil dari file extension.yaml dan PREINSTALL.md:

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

Semua file README untuk ekstensi Firebase resmi dibuat menggunakan perintah tersebut.

Menambahkan informasi penginstalan

Setelah Anda menulis atau membuat README, tambahkan informasi penginstalan pada README. Anda dapat menggunakan cuplikan berikut sebagai template:

---

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

---

Menulis file PREINSTALL

File PREINSTALL adalah ringkasan ekstensi Anda, yaitu sejenis halaman "pemasaran".

Konten apa yang ada dalam file ini?

• Deskripsi lengkap fungsionalitas ekstensi Anda
• Daftar prasyarat, seperti penyiapan database atau akses ke layanan non-Google (contoh)
• Deskripsi singkat semua tugas pra-penginstalan dan petunjuknya
• Deskripsi singkat semua tugas pasca-penginstalan (contoh) (petunjuk terperinci dapat dilihat di POSTINSTALL)
• Deskripsi singkat semua implikasi penagihan (dimulai dengan teks boilerplate)

Di mana konten ini ditampilkan kepada pengguna?

• Di halaman ekstensi di extensions.dev.
• Repositori kode sumber untuk ekstensi Anda (di dalam direktori ekstensi)
• Sebagai bagian dari README ekstensi (jika Anda menggunakan flag --markdown > README.md Firebase CLI)

File PREINSTALL tidak dapat mengakses parameter value untuk ekstensi, jadi jangan berharap referensi parameter akan dirender dengan nilai sebenarnya.

Apa saja praktik terbaik?

• Batasi isi lengkap file PREINSTALL di bawah satu halaman, jika memungkinkan
• Sediakan level detail yang benar-benar perlu diketahui pengguna akhir sebelum menginstal ekstensi
• Cantumkan petunjuk terperinci dalam file POSTINSTALL atau file tambahan lainnya
• Sebutkan secara singkat apakah Anda menyediakan alat atau skrip lain untuk mendukung ekstensi

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

Menulis file POSTINSTALL

File POSTINSTALL adalah halaman petunjuk pasca-penginstalan terperinci untuk ekstensi Anda.

Konten apa yang ada dalam file ini?

• Petunjuk terperinci semua tugas pasca-penginstalan yang diperlukan, seperti menyiapkan aturan keamanan Firebase atau menambahkan kode sisi klien (contoh)
• Petunjuk umum tentang cara untuk segera mencoba ekstensi yang diinstal (contohnya, "buka konsol, lalu lakukan ini")
• Informasi dasar tentang cara memicu ekstensi, terutama untuk ekstensi yang dipicu permintaan HTTP
• Petunjuk singkat tentang cara memantau ekstensi yang diinstal (dimulai dengan teks boilerplate)

Di mana konten ini ditampilkan kepada pengguna?

• Di Firebase console setelah pengguna menginstal ekstensi Anda (di kartu detail ekstensi yang diinstal)

  • Pastikan Anda meninjau tampilan konten POSTINSTALL dengan menginstal ekstensi di project sebenarnya.

• Repositori kode sumber untuk ekstensi Anda (di dalam direktori ekstensi)

File POSTINSTALL dapat mengakses parameter value dan beberapa variabel terkait fungsi untuk ekstensi. Saat konten POSTINSTALL ditampilkan di Firebase console, nilai sebenarnya akan ditampilkan, bukan referensi parameter atau variabel. Pelajari lebih lanjut cara mereferensikan parameter dan variabel dalam file POSTINSTALL Anda di bawah.

Apa saja praktik terbaik?

• Buat konten lengkap file POSTINSTALL tetap ringkas, tetapi deskriptif.
• Kelompokkan konten menggunakan judul untuk memisahkan tugas atau konsep yang berbeda.
• Pertimbangkan untuk memublikasikan petunjuk terperinci terkait alur kerja atau tugas tertentu di situs Anda (contoh) atau dalam file markdown tambahan dalam repositori ekstensi (contoh ).
• Referensikan parameter dan variabel terkait fungsi sehingga pengguna melihat nilai yang dikonfigurasi dalam konteks petunjuk

Mereferensikan parameter dan variabel

Setelah penginstalan, Firebase console akan menampilkan isi file POSTINSTALL ekstensi. Jika Anda mereferensikan parameter dan variabel terkait fungsi (lihat tabel di bawah) di file POSTINSTALL, maka konsol akan mengisi referensi ini dengan nilai sebenarnya untuk instance yang diinstal.

Akses parameter value yang dikonfigurasi dalam file POSTINSTALL menggunakan sintaksis berikut: ${param:PARAMETER_NAME}

Anda juga dapat mereferensikan variabel terkait fungsi berikut dalam file POSTINSTALL saja. Firebase mendukung variabel ini sehingga Anda dapat lebih mudah memberikan panduan bagi pengguna pasca-penginstalan. Variabel ini hanya tersedia untuk digunakan dalam file POSTINSTALL karena nilainya baru tersedia setelah penginstalan.

Dalam tabel ini, function-name adalah nilai untuk kolom name di objek resource fungsi dalam 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.

Mendokumentasikan cara memicu ekstensi

Dalam dokumentasi pengguna ekstensi, Anda perlu memberikan petunjuk kepada pengguna tentang cara memicu ekstensi. Petunjuk ini dapat sangat terperinci, jika menurut Anda perlu, tetapi ingatlah praktik terbaik dalam menulis file POSTINSTALL. Untuk panduan cara memberikan petunjuk ini, perluas bagian di bawah yang sesuai dengan ekstensi Anda.

Menulis file CHANGELOG

Konten apa yang ada dalam file ini?

Setiap ekstensi harus memiliki file CHANGELOG.md yang mendokumentasikan perubahan yang disertakan dalam setiap versi baru ekstensi yang Anda publikasikan. Letakkan setiap versi di bawah header level 2 (##); jika tidak, Anda dapat menggunakan pemformatan Markdown yang Anda sukai.

Contoh berikut adalah kutipan dari salah satu ekstensi resmi:

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

Di mana konten ini ditampilkan kepada pengguna?

• Di Firebase console dan CLI, saat pengguna melakukan upgrade ke versi ekstensi yang baru. Firebase console dan CLI hanya menampilkan perubahan yang akan diterapkan jika pengguna ingin menyelesaikan upgrade.
• Repositori kode sumber ekstensi Anda (di dalam direktori ekstensi).