יצירת תיעוד למשתמשים עבור התוסף

לכל תוסף חייבת להיות תיעוד שמסביר למשתמשים מה התוסף עושה ואיך משתמשים בו.

התיעוד המינימלי שנדרש הוא קבוצה של שלושה קובצי Markdown:

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

בנוסף, כדאי לשקול גם ליצור:

• קובץ README למאגר הציבורי של התוסף.
• מדריכים, הנחיות וחומר עזר ארוכים יותר שפורסמו באתר שלכם ומקושרים ב-PREINSTALL.md.

כדי ללמוד על שיטות מומלצות ועל ניסוח ומבנה נפוצים, מומלץ לעיין בקבצים שזמינים בתוספים הרשמיים של Firebase.

יצירת קובץ README

ספריית התוסף יכולה להכיל קובץ README. הערה: הפקודה firebase ext:dev:init לא יוצרת באופן אוטומטי קובץ כזה בשבילכם.

עם זאת, ב-CLI של Firebase יש תמיכה בפקודה הנוחה הבאה ליצירה אוטומטית של קובץ README שמכיל תוכן שנלקח מקובץ extension.yaml ומקובץ PREINSTALL.md:

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

כל קובצי ה-README של התוספים הרשמיים של Firebase נוצרים באמצעות הפקודה הזו.

הוספת פרטי התקנה

אחרי שכותבים או יוצרים קובץ README, מוסיפים לו מידע על ההתקנה. אפשר להשתמש בקטע הקוד הבא כתבנית:

---

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

---

כתיבת קובץ PREINSTALL

קובץ PREINSTALL הוא סקירה כללית של התוסף, סוג של דף שיווקי.

מה התוכן בקובץ הזה?

• תיאור מקיף של הפונקציונליות של התוסף
• רשימת דרישות מוקדמות, כמו הגדרת מסד נתונים או גישה לשירות שאינו של Google (דוגמה)
• תיאור קצר של משימות לפני ההתקנה וההוראות שלהן
• תיאור קצר של משימות שצריך לבצע אחרי ההתקנה (דוגמה) (הוראות מפורטות מופיעות ב-POSTINSTALL)
• תיאור קצר של ההשלכות על החיוב (מתחילים עם טקסט מוכן)

איפה התוכן הזה מוצג למשתמש?

מסוף Firebase">

מסוף Firebase">

• בדף התוסף באתר extensions.dev.
• מאגר קוד המקור של התוסף (בתוך ספריית התוסף)
• כחלק מקובץ ה-README של התוסף (אם משתמשים בדגל --markdown > README.md של ה-CLI של Firebase)

לקובצי PREINSTALL אין גישה לערכי הפרמטרים של התוסף, ולכן לא צפוי שייצוגים של פרמטרים יופיעו עם ערכים בפועל.

מהן כמה שיטות מומלצות?

• אם אפשר, צריך לשמור את התוכן המלא של הקובץ PREINSTALL בדף אחד,
• צריך לספק את רמת הפירוט שמשתמש קצה חייב לדעת לפני שהוא מתקין את התוסף
• כדאי לצרף הוראות מפורטות בPOSTINSTALLקובץ או בקבצים משלימים אחרים
• אם אתם מספקים כלים או סקריפטים אחרים לתמיכה בתוסף, ציינו זאת בקצרה.

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

כתיבת קובץ POSTINSTALL

קובץ POSTINSTALL הוא דף הוראות מפורט של התוסף אחרי ההתקנה.

מה התוכן בקובץ הזה?

• הוראות מפורטות לכל המשימות הנדרשות אחרי ההתקנה, כמו הגדרת כללי אבטחה של Firebase או הוספת קוד בצד הלקוח (דוגמה)
• הוראות כלליות לניסיון מיידי של התוסף המותקן (לדוגמה, 'עוברים למסוף ואז עושים את הפעולה הבאה')
• מידע בסיסי על הפעלת התוסף, במיוחד לגבי תוספים שמופעלים על ידי בקשת HTTP
• הוראות קצרות למעקב אחרי התוסף המותקן (מתחילים עם טקסט מוכן מראש)

איפה התוכן הזה מוצג למשתמש?

מסוף Firebase">

מסוף Firebase">

• במסוף Firebase אחרי שמשתמש מתקין את התוסף (בכרטיס הפרטים של התוסף המותקן)

  • חשוב לבדוק את התוכן של POSTINSTALL על ידי התקנת התוסף בפרויקט בפועל.

• מאגר קוד המקור של התוסף (בתוך ספריית התוסף)

קבצים POSTINSTALL יכולים לגשת לערכי הפרמטרים ולכמה משתנים שקשורים לפונקציה של התוסף. כשתוכן POSTINSTALL מוצג במסוף Firebase, מוצגים הערכים בפועל ולא הפניות לפרמטר או למשתנה. בהמשך מוסבר איך מפנים לפרמטרים ולמשתנים בקובץ POSTINSTALL.

מהן כמה שיטות מומלצות?

• התוכן המלא של קובץ POSTINSTALL צריך להיות תמציתי אבל תיאורי.
• כדאי לחלק את התוכן באמצעות כותרות כדי להפריד בין משימות או מושגים שונים.
• כדאי לפרסם באתר הוראות מפורטות לגבי תהליך עבודה או משימה ספציפיים (דוגמה) או בקובצי markdown משלימים במאגר התוספים (דוגמה).
• הפניה לפרמטרים ולמשתנים שקשורים לפונקציות כדי שהמשתמש יראה את הערכים שהוגדרו בהקשר של ההוראות

הפניה לפרמטרים ולמשתנים

אחרי ההתקנה, במסוף Firebase מוצג התוכן של קובץ POSTINSTALL התוסף. אם אתם מפנים לפרמטרים ולמשתנים שקשורים לפונקציה (ראו את הטבלה בהמשך) בקובץ POSTINSTALL, המסוף מאכלס את ההפניות האלה בערכים בפועל של המופע המותקן.

אפשר לגשת לערכי הפרמטר שהוגדרו בקובץ POSTINSTALL באמצעות התחביר הבא: ${param:PARAMETER_NAME}

אפשר גם להפנות למשתנים הבאים שקשורים לפונקציה רק בקובץ POSTINSTALL. פלטפורמת Firebase תומכת במשתנים האלה כדי שתוכלו לספק למשתמשים שלכם הנחיות בקלות רבה יותר אחרי ההתקנה. אפשר להשתמש בהם רק בקובץ POSTINSTALL כי הערכים של המשתנים האלה זמינים רק אחרי ההתקנה.

בטבלה הזו, function-name הוא הערך של השדה name באובייקט המשאב של הפונקציה בתוך 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.

תיעוד של אופן ההפעלה של תוסף

בתיעוד למשתמשים של התוסף, צריך להסביר למשתמשים איך להפעיל את התוסף. ההוראות יכולות להיות מפורטות ככל שנדרש, אבל חשוב לזכור את השיטות המומלצות לכתיבת קובץ POSTINSTALL. כדי לקבל הנחיות לגבי אופן מתן ההוראות האלה, מרחיבים את הקטע הרלוונטי לתוסף שלכם שבהמשך.

כתיבת קובץ יומן שינויים

מה התוכן בקובץ הזה?

לכל תוסף צריך להיות קובץ CHANGELOG.md שמתעד את השינויים שנכללים בכל גרסה חדשה של התוסף שאתם מפרסמים. מציבים כל גרסה מתחת לכותרת ברמה 2 (##). אפשר להשתמש בכל עיצוב Markdown שרוצים.

הדוגמה הבאה היא קטע מתוך אחת מהתוספים הרשמיים:

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

איפה התוכן הזה מוצג למשתמש?

• במסוף Firebase וב-CLI, כשמשתמשים משדרגים לגרסאות חדשות של התוסף. במסוף Firebase וב-CLI מוצגים רק השינויים שייכנסו לתוקף אם המשתמש ישלים את השדרוג.
• מאגר קוד המקור של התוסף (בתוך ספריית התוסף).