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

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

המסמכים המינימליים הנדרשים הם שלושת קובצי ה-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)
• תיאור קצר של ההשלכות על החיוב (מתחילים ב-boilerplate text)

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

מסוף Firebase">

מסוף Firebase">

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

לא ניתן לגשת לערכים של הפרמטרים של התוסף בקובצי 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 פרמטרים ומשתנים שקשורים לפונקציות (ראו טבלה בהמשך), מסוף ה-CLI מאכלס את ההפניות האלה בערכים האמיתיים של המכונה המותקנת.

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

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

בטבלה הזו, הערך של השדה name באובייקט המשאב של הפונקציה ב-extension.yaml הוא function-name.

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

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

לכל תוסף חייב להיות קובץ 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 מוצגים רק השינויים שיחולו אם המשתמש ישלים את השדרוג.
• המאגר של קוד המקור של התוסף (בתוך ספריית התוסף).