สร้างเอกสารประกอบผู้ใช้สำหรับส่วนขยายของคุณ

ส่วนขยายทุกรายการต้องมีเอกสารประกอบที่สอนผู้ใช้ว่าส่วนขยาย ทำอะไรได้บ้างและวิธีใช้งาน

เอกสารขั้นต่ำที่จำเป็นคือชุดไฟล์ Markdown 3 ไฟล์นี้

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

นอกจากนี้ คุณควรพิจารณาผลิตเนื้อหาต่อไปนี้ด้วย

• ไฟล์ README สำหรับที่เก็บข้อมูลสาธารณะของส่วนขยาย
• บทแนะนำ คำแนะนำ และข้อมูลอ้างอิงแบบยาวที่เผยแพร่ในเว็บไซต์ของคุณเองและ ลิงก์ใน PREINSTALL.md

หากต้องการดูแนวทางปฏิบัติแนะนำ รวมถึงวลีและโครงสร้างที่ใช้กันโดยทั่วไป เราขอแนะนำให้ตรวจสอบไฟล์ที่พร้อมใช้งานกับส่วนขยายFirebaseอย่างเป็นทางการ

การสร้าง README

ไดเรกทอรีส่วนขยายอาจมี README หรือไม่มีก็ได้ โปรดทราบว่าคำสั่ง firebase ext:dev:init จะไม่สร้างไฟล์ให้คุณโดยอัตโนมัติ

อย่างไรก็ตาม Firebase CLI รองรับคำสั่งอำนวยความสะดวกต่อไปนี้เพื่อ สร้างไฟล์ 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 ของส่วนขยาย (หากคุณใช้แฟล็ก 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 คอนโซลจะป้อนค่าจริงสำหรับอินสแตนซ์ที่ติดตั้งแล้วลงในการอ้างอิงเหล่านี้

เข้าถึงค่าพารามิเตอร์ที่กำหนดค่าไว้ในไฟล์ 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

ไฟล์นี้มีเนื้อหาอะไร

ส่วนขยายทุกรายการต้องมีไฟล์ 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 จะแสดงเฉพาะการเปลี่ยนแปลงที่จะมีผลหากผู้ใช้อัปเกรดเสร็จสมบูรณ์
• ที่เก็บซอร์สโค้ดของส่วนขยาย (ภายในไดเรกทอรีส่วนขยาย)