คู่มือทีม Docs Engineering

สร้าง User Manual
ด้วย AI

workflow ที่ใช้จริงบน Docusaurus — จาก spec ดิบ สู่คู่มือที่ลูกค้าอ่านเข้าใจ ด้วย AI เป็นคนขับ

6 ระยะภาษาเชิงธุรกิจ Visual-firstAI-assisted

ทำไมต้องมี workflow

AI เขียนเร็ว แต่ "เขียนถูก" ต้องมีระเบียบ

ปล่อย AI เขียนลอยๆ = คู่มือผิด, แก้ผิดไฟล์, spec ล้าหลัง — workflow นี้กันพลาด 3 จุดใหญ่

ข้อมูลล้าหลัง

Spec ใน docs อาจเก่ากว่า service → sync ก่อนเสมอ

แก้ผิดไฟล์

AI เดา path จากชื่อ → grep ยืนยันก่อนแก้

ภาษา dev หลุด

คุมโทนให้เป็นคำที่ลูกค้าเข้าใจเชิงธุรกิจ

หลักการตั้งต้น

4 กติกา ก่อนปล่อยให้ AI เขียน

ยึดทุกครั้ง ไม่มีข้อยกเว้น

อ่านได้ ≠ แก้ได้

source code = อ่านอย่างเดียว แก้เฉพาะ docs ให้ตรง code

Sync spec ก่อน

ดึง spec ล่าสุดก่อนแตะ API field / schema / endpoint

grep ยืนยัน path

ห้ามเดาจากชื่อไฟล์ — ไม่เจอให้บอก ไม่เดาแล้วแก้

เขียนให้เข้าใจ "ทำไม"

ครบ logic, สถานะ, timing, edge case, ข้ามระบบ

แพลตฟอร์ม

Docusaurus vs Astro

คู่มือชุดนี้ใช้ Docusaurus — รู้ทั้งคู่ไว้เลือกถูกเวลาขึ้นโปรเจกต์ใหม่

📘 Docusaurus ที่ใช้อยู่

เครื่องมือ docs ครบชุด (React/Meta): sidebar, versioning, search, admonition พร้อมใช้ · เขียน MDX + Infima card · แลกกับ bundle ใหญ่และปรับ theme ลึกยากกว่า

🚀 Astro (Starlight)

เว็บทั่วไป + theme Starlight: เบา เร็ว ส่ง HTML ล้วน คุม performance/design อิสระ · แต่ฟีเจอร์ docs เฉพาะทางต้องประกอบเอง

หลักการ workflow ทั้งหมดในสไลด์นี้ใช้ได้กับทั้งสองตัว

ภาพรวม

เส้นทาง 6 ระยะ

เรียงตามลำดับที่ทำงานจริง

01Sync context

02grep ยืนยัน path

03Draft ภาษาลูกค้า

04Visual card/table

05New badge

06Review & push

ระยะ 01 Sync context

ป้อน source ที่สด & ถูกให้ AI ก่อน

รู้ว่า repo ไหน แก้ได้ / อ่านอย่างเดียว
รัน sync script เป็นนิสัย (npm run sync:specs)
หา source of truth: OpenAPI/AsyncAPI, architecture, BA context

🤖 promptอ่าน spec นี้ [openapi.yaml] + architecture doc สรุป flow, ทุกสถานะ, field สำคัญ ยังไม่ต้องเขียน docs — ยืนยันความเข้าใจก่อน

ระยะ 02 ยืนยัน path

grep ก่อนแตะไฟล์ทุกครั้ง

grep ข้อความบน UI จริง ไม่ใช่เดาจากชื่อ
ชื่อไฟล์ ≠ component ที่ render เสมอไป
grep ไม่เจอ → หยุด แล้วถาม ไม่เดาต่อ

🤖 promptgrep หาไฟล์ที่ render ข้อความ "..." ก่อนแก้ ยืนยัน path จริงให้ดู แล้วค่อยเสนอ diff หาไม่เจอบอกตรงๆ ห้ามเดา

ระยะ 03 Draft

เขียนด้วยภาษาลูกค้า ไม่ใช่ภาษา dev

เล่าเป็น "ผู้ใช้ทำอะไร" ไม่ใช่ "ระบบ config อะไร"
ครบทุก flow: logic, สถานะ, timing, edge case, ข้ามระบบ
รีวิว draft เทียบ spec — จับจุดที่ AI แต่งเกิน

🤖 promptเขียนหน้าคู่มือจาก spec ที่อ่านไป ใช้ภาษาที่ลูกค้าเข้าใจเชิงธุรกิจ อย่าใช้ศัพท์ dev ครอบคลุม: เงื่อนไข, ทุกสถานะ, ลำดับเวลา, กรณีพิเศษ

ระยะ 04 Visual

Card + status + table ช่วยอ่าน

Step/Status card ด้วย Infima grid (row / col)
color-code สถานะด้วย borderLeft ตามสีมาตรฐาน
ตารางเขียวเข้ม, ตัวหนังสือคม, ภาพขอบเขียว
JSX-style style={{...}}, เลี่ยง nested list ใน HTML

🤖 promptแปลง flow นี้เป็น status card color-coded ใช้ชุดสีมาตรฐาน + Infima grid, style JSX-style edge case ใช้ Markdown table ปกติพอ

ระยะ 05 New badge

ฟีเจอร์ใหม่ต้องหาง่าย

เมนู/ฟีเจอร์อัปเดต ≤ 60 วัน → ติดป้าย "New"
เขียนกล่องสรุปว่ามีอะไรใหม่ ด้วยคำเชิงธุรกิจ
อัปเดต changelog ให้สอดคล้อง

🤖 promptเมนูไหนอัปเดตไม่เกิน 60 วัน ติดป้าย New เขียนกล่องอธิบายว่ามีอะไรใหม่ เน้นประโยชน์เชิงธุรกิจ sync กับ changelog ด้วย

ระยะ 06 Review & push

ดูของจริงก่อน แล้วค่อย commit

preview Docusaurus + screenshot หลาย breakpoint
เช็คความคมตัวอักษร / สีตาราง / ขอบภาพ / overflow
commit แบบ docs: ... แล้ว push (เลือก gh ให้ตรง org)

🤖 promptstart preview แล้ว screenshot ที่ 375 / 768 / 1440 ตรวจ overflow และความคมของสี ถ้าโอเค commit แบบ docs: แล้ว push

มาตรฐานทีม

ชุดสีสถานะ

ใช้ซ้ำทุกหน้า เพื่อให้คู่มือดูเป็นระบบเดียวกัน

รอดำเนินการ #9b59b6

รออนุมัติ #3498db

รอฝ่ายอื่น #f39c12

อนุมัติ/รอโอน #e67e22

สำเร็จ #27ae60

ปฏิเสธ/error #e74c3c

ก่อนปิดงานทุกหน้า

Checklist 10 ข้อ

Sync spec ล่าสุดแล้ว
ยืนยัน path ด้วย grep แล้ว
ครบทุก flow & edge case
ภาษาเชิงธุรกิจ ไม่มีศัพท์ dev หลุด
Flow ซับซ้อนมี card/visual ช่วยอ่าน
สถานะใช้สีมาตรฐาน
ป้าย New ครบ (ฟีเจอร์ ≤ 60 วัน)
ตัวหนังสือคม / ตารางเขียว / ขอบภาพเขียว
Preview หลาย breakpoint ไม่ overflow
Commit conventional แล้ว push

สรุป

AI เร็ว — ระเบียบ ทำให้ถูก

Sync → grep → draft ภาษาธุรกิจ → visual → New → review. ทำซ้ำจนเป็นนิสัย แล้วคู่มือจะออกมาเป็นระบบเดียวกันทุกหน้า

เริ่มที่ระยะ 01 เสมอไม่เดา pathคิดถึงลูกค้า