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

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

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

• 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 )
• คำอธิบายโดยย่อเกี่ยวกับผลกระทบในการเรียกเก็บเงิน (เริ่มต้นด้วย ข้อความสำเร็จรูป )

เนื้อหานี้แสดงต่อผู้ใช้ที่ไหน?

• ในหน้าส่วนขยายบน 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 หลังจากที่ผู้ใช้ติดตั้งส่วนขยายของคุณ (ในการ์ดรายละเอียดของส่วนขยายที่ติดตั้ง)

  • ตรวจสอบให้แน่ใจว่าได้ตรวจสอบการแสดงเนื้อหา POSTINSTALL โดย การติดตั้งส่วนขยายของคุณในโครงการจริง

• ที่เก็บซอร์สโค้ดของคุณสำหรับส่วนขยายของคุณ (ภายในไดเร็กทอรีส่วนขยาย)

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

แนวทางปฏิบัติที่ดีที่สุดมีอะไรบ้าง?

• เก็บเนื้อหาทั้งหมดของไฟล์ POSTINSTALL ให้กระชับ แต่สื่อความหมายได้
• แบ่งเนื้อหาโดยใช้ส่วนหัวเพื่อแยกงานหรือแนวคิดที่แตกต่างกันออกไป
• ลองเผยแพร่คำแนะนำโดยละเอียดสำหรับเวิร์กโฟลว์หรืองานเฉพาะบนเว็บไซต์ของคุณ ( ตัวอย่าง ) หรือในไฟล์มาร์กดาวน์เสริมภายในที่เก็บส่วนขยาย ( ตัวอย่าง )
• พารามิเตอร์อ้างอิงและตัวแปรที่เกี่ยวข้องกับฟังก์ชัน เพื่อให้ผู้ใช้เห็นค่าที่กำหนดค่าไว้ในบริบทของคำแนะนำ

การอ้างอิงพารามิเตอร์และตัวแปร

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