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?

Gambar konten pra-penginstalan di <span class=Firebase console">
Konten pra-penginstalan di Firebase console

Gambar besar konten pra-penginstalan di <span class=Firebase console">

  • 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

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?

Gambar konten pasca-penginstalan di <span class=Firebase console">
Konten pasca-penginstalan di Firebase console

Gambar besar konten pasca-penginstalan di <span class=Firebase console">

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

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

Referensi untuk variabel terkait fungsi Deskripsi Nilai variabel (diisi otomatis oleh Firebase setelah ekstensi diinstal)
${function:function-name.location}
Lokasi fungsi di-deploy Contoh nilai:
us-central1
${function:function-name.name}
Nama fungsi akhir yang di-deploy, yang menyertakan ID instance ekstensi

Format umum:
ext-extension-instance-id-function-name

Contoh nilai:
ext-my-awesome-extension-6m31-yourFunctionName

${function:function-name.url} (hanya berlaku untuk fungsi HTTP)
URL dari fungsi akhir yang di-deploy, yang dapat menerima permintaan HTTP dari kode klien

Format umum:
https://deployment-location-project-id.cloudfunctions.net/name-of-final-deployed-function

Contoh nilai:
https://us-central1-project-123.cloudfunctions.net/ext-my-awesome-extension-6m31-yourFunctionName

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