Utwórz dokumentację użytkownika dla swojego rozszerzenia

Każde rozszerzenie musi mieć dokumentację, która uczy użytkowników, co robi rozszerzenie i jak z niego korzystać.

Minimalna wymagana dokumentacja to zestaw trzech plików przecen:

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

Ponadto należy rozważyć produkcję:

• Plik README dla publicznego repozytorium rozszerzenia.
• Dłuższe samouczki, przewodniki i odniesienia opublikowane na Twojej własnej stronie internetowej i połączone w pliku PREINSTALL.md .

Aby poznać najlepsze praktyki oraz typowe sformułowania i strukturę, zalecamy przejrzenie plików dostępnych z oficjalnymi rozszerzeniami Firebase .

Tworzenie pliku README

Twój katalog rozszerzeń może opcjonalnie zawierać plik README. Pamiętaj, że polecenie firebase ext:dev:init nie generuje go automatycznie.

Interfejs Firebase CLI obsługuje jednak następujące wygodne polecenie automatycznego generowania pliku README zawierającego treść pobraną z pliku extension.yaml i pliku PREINSTALL.md :

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

Wszystkie pliki README dla oficjalnych rozszerzeń Firebase są generowane za pomocą tego polecenia.

Dodaj informacje o instalacji

Po napisaniu lub wygenerowaniu pliku README dodaj do niego informacje dotyczące instalacji. Możesz użyć następującego fragmentu jako szablonu:

---

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

---

Zapisywanie pliku PREINSTALL

Plik PREINSTALL to przegląd Twojego rozszerzenia, rodzaj strony „marketingowej”.

Jaka zawartość znajduje się w tym pliku?

• Kompleksowy opis funkcjonalności Twojego rozszerzenia
• Lista wymagań wstępnych, takich jak konfiguracja bazy danych lub dostęp do usługi innej niż Google ( przykład )
• Krótki opis wszelkich zadań przedinstalacyjnych i ich instrukcji
• Krótki opis wszelkich zadań poinstalacyjnych ( przykład ) (szczegółowe instrukcje znajdują się w POSTINSTALL )
• Krótki opis wszelkich konsekwencji rozliczeniowych (zacznij od standardowego tekstu )

Gdzie ta treść jest wyświetlana użytkownikowi?

• Na stronie rozszerzenia w witrynie rozszerzenia.dev .
• Repozytorium kodu źródłowego Twojego rozszerzenia (w katalogu rozszerzenia)
• Jako część pliku README rozszerzenia (jeśli używasz interfejsu CLI Firebase --markdown > README.md )

Pliki PREINSTALL nie mają dostępu do wartości parametrów rozszerzenia, dlatego nie należy oczekiwać, że odniesienia do parametrów będą renderowane z rzeczywistymi wartościami.

Jakie są najlepsze praktyki?

• Jeśli to możliwe, przechowuj pełną zawartość pliku PREINSTALL na jednej stronie
• Podaj poziom szczegółowości, który użytkownik końcowy musi znać przed zainstalowaniem rozszerzenia
• Umieść szczegółowe instrukcje w pliku POSTINSTALL lub innych plikach uzupełniających
• Krótko wspomnij, czy udostępniasz inne narzędzia lub skrypty do obsługi rozszerzenia

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

Zapisywanie pliku POSTINSTALL

Plik POSTINSTALL to szczegółowa strona z instrukcjami poinstalacyjnymi dla Twojego rozszerzenia.

Jaka zawartość znajduje się w tym pliku?

• Szczegółowe instrukcje dotyczące wszelkich wymaganych zadań poinstalacyjnych, takich jak konfigurowanie reguł bezpieczeństwa Firebase lub dodawanie kodu po stronie klienta ( przykład )
• Ogólne instrukcje dotyczące natychmiastowego wypróbowania zainstalowanego rozszerzenia (na przykład „przejdź do konsoli, a następnie wykonaj to”)
• Podstawowe informacje o tym, jak uruchomić rozszerzenie, szczególnie w przypadku rozszerzeń uruchamianych żądaniem HTTP
• Krótkie wskazówki dotyczące monitorowania zainstalowanego rozszerzenia (zacznij od tekstu schematycznego )

Gdzie ta treść jest wyświetlana użytkownikowi?

• W konsoli Firebase po zainstalowaniu przez użytkownika rozszerzenia (na karcie szczegółów zainstalowanego rozszerzenia)

  • Upewnij się, że sprawdziłeś wyświetlanie zawartości POSTINSTALL , instalując rozszerzenie w rzeczywistym projekcie .

• Repozytorium kodu źródłowego Twojego rozszerzenia (w katalogu rozszerzenia)

Pliki POSTINSTALL mogą uzyskać dostęp do wartości parametrów i kilku zmiennych związanych z funkcjami rozszerzenia. Gdy w konsoli Firebase wyświetlana jest treść POSTINSTALL , wyświetlane są rzeczywiste wartości , a nie odwołania do parametrów lub zmiennych. Poniżej dowiesz się więcej o tym, jak odwoływać się do parametrów i zmiennych w pliku POSTINSTALL .

Jakie są najlepsze praktyki?

• Zachowaj zwięzłą, ale opisową pełną zawartość pliku POSTINSTALL .
• Podziel treść za pomocą nagłówków, aby rozdzielić odrębne zadania lub koncepcje.
• Rozważ opublikowanie szczegółowych instrukcji dotyczących konkretnego przepływu pracy lub zadania na swojej stronie internetowej ( przykład ) lub w dodatkowych plikach przecen w repozytorium rozszerzeń ( przykład ).
• Parametry referencyjne i zmienne związane z funkcjami , aby użytkownik widział ich skonfigurowane wartości w kontekście instrukcji

Odwoływanie się do parametrów i zmiennych

Po instalacji konsola Firebase wyświetla zawartość pliku POSTINSTALL rozszerzenia. Jeśli w pliku POSTINSTALL odwołujesz się do parametrów i zmiennych związanych z funkcjami (patrz tabela poniżej), konsola wypełnia te odniesienia rzeczywistymi wartościami zainstalowanej instancji.

Uzyskaj dostęp do skonfigurowanych wartości parametrów w pliku POSTINSTALL , korzystając z następującej składni: ${param: PARAMETER_NAME }

Możesz także odwoływać się do następujących zmiennych związanych z funkcjami , tylko w pliku POSTINSTALL . Firebase obsługuje te zmienne, dzięki czemu możesz łatwiej udzielać użytkownikom wskazówek po instalacji. Można ich używać tylko w pliku POSTINSTALL , ponieważ wartości tych zmiennych są dostępne dopiero po instalacji.

W tej tabeli function-name jest wartością pola name w obiekcie zasobu funkcji w pliku 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.

Dokumentowanie sposobu uruchomienia rozszerzenia

W dokumentacji użytkownika rozszerzenia musisz poinstruować użytkowników, jak uruchomić rozszerzenie. Instrukcje te mogą być tak szczegółowe, jak uznasz to za konieczne, ale pamiętaj o najlepszych praktykach pisania pliku POSTINSTALL . Aby uzyskać wskazówki dotyczące podawania tych instrukcji, rozwiń poniższą sekcję dotyczącą Twojego rozszerzenia.

Zapisywanie pliku CHANGELOG

Jaka zawartość znajduje się w tym pliku?

Każde rozszerzenie musi mieć plik CHANGELOG.md , który dokumentuje zmiany zawarte w każdej nowej wersji Twojego rozszerzenia, którą publikujesz. Umieść każdą wersję pod nagłówkiem poziomu 2 ( ## ); w przeciwnym razie możesz użyć dowolnego formatowania Markdown.

Poniższy przykład jest fragmentem jednego z oficjalnych rozszerzeń:

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

Gdzie ta treść jest wyświetlana użytkownikowi?

• W konsoli Firebase i CLI, gdy użytkownicy uaktualnią Twoje rozszerzenie do nowych wersji. Konsola Firebase i interfejs CLI wyświetlają tylko zmiany, które weszły w życie, gdyby użytkownik ukończył aktualizację.
• Repozytorium kodu źródłowego Twojego rozszerzenia (w katalogu rozszerzenia).