แนวทางการเขียนคู่มือ

คู่มือควรอธิบายงานจากมุมมองผู้ใช้ ไม่ผูกกับรายละเอียด implementation ที่ผู้ใช้ไม่จำเป็นต้องรู้

ก่อนเริ่มหน้าใหม่ ให้ตรวจลำดับความสำคัญและสถานะจาก แผนจัดทำ User Manual และอัปเดต checklist เมื่อเนื้อหาผ่านการตรวจสอบแล้ว

รูปแบบที่แนะนำ

1. เริ่มด้วยผลลัพธ์ที่ผู้ใช้จะทำได้
2. ระบุสิทธิ์หรือเงื่อนไขก่อนเริ่ม
3. เขียนขั้นตอนเป็นรายการลำดับเลข
4. ใช้ชื่อปุ่มและเมนูตรงกับข้อความในระบบ
5. อธิบายผลลัพธ์หลังยืนยัน
6. เพิ่มวิธีแก้ปัญหาที่พบบ่อย

ขอบเขต Happy path และ Negative path

ทุกหน้าต้องมี happy path ที่พาผู้ใช้ไปถึงผลลัพธ์หลัก สำหรับ flow สำคัญระดับ P0-P1 ต้องเพิ่มเฉพาะ negative path ที่ผู้ใช้มีโอกาสพบและมีวิธีแก้ไขหรือส่งต่อได้จริง โดยอย่างน้อยให้พิจารณา:

• validation ที่ผู้ใช้แก้เองได้
• สถานะธุรกิจที่ทำต่อไม่ได้ เช่น บัญชีถูกล็อก รหัสผ่านหมดอายุ หรืองานสิ้นสุดแล้ว
• permission หรือข้อมูลตั้งต้นไม่พร้อม
• session/network error และสิ่งที่เกิดกับข้อมูลที่ยังไม่ได้บันทึก
• ข้อมูลที่ต้องแนบและข้อมูลที่ห้ามส่งเมื่อขอความช่วยเหลือ

ไม่จำเป็นต้องเผยแพร่ test case เชิงเทคนิคทุกกรณีในคู่มือผู้ใช้ และห้ามใส่ mock credential, API error code, token หรือรายละเอียดภายในที่ผู้ใช้ไม่ต้องใช้ตัดสินใจ

การจัดหมวดหมู่และตั้งชื่อเมนู

• จัดหมวดตามงานที่ผู้ใช้ต้องการทำ ไม่จัดตามชื่อ route หรือโครงสร้าง source code
• ใช้ชื่อหมวดหลักให้คงที่: เริ่มต้นใช้งาน, งานของผู้ใช้งาน, งานผู้ดูแลระบบ, ช่วยเหลือและแก้ปัญหา และ สำหรับทีมจัดทำคู่มือ
• ใช้ภาษาไทยเป็นหลัก และคงคำศัพท์ของระบบ เช่น Collection หรือ Worklist เมื่อช่วยให้ตรงกับ UI
• ไม่สร้างหมวดย่อยที่มีหน้าเดียวโดยไม่มีแผนเพิ่มเนื้อหา
• หนึ่งหน้าควรปรากฏใน sidebar เพียงตำแหน่งหลักเดียว แล้วใช้ลิงก์ในเนื้อหาเชื่อมจากหัวข้อที่เกี่ยวข้อง

การใช้ภาพหน้าจอ

• เก็บไฟล์ใน docs/public/images/
• ใช้ชื่อภาษาอังกฤษตัวพิมพ์เล็กคั่นด้วยขีด เช่น login-screen.png
• ครอบเฉพาะส่วนที่จำเป็นและต้องอ่านตัวอักษรได้
• ปิดบังชื่อ เบอร์โทร เลขบัญชี token และข้อมูลส่วนบุคคล
• ใส่ alt text ที่อธิบายหน้าจอ เช่น:

![หน้าจอเลือก Collection](/images/select-collection.png)

Callout ที่ใช้ได้

::: tip เคล็ดลับ
คำแนะนำที่ช่วยให้ทำงานได้เร็วขึ้น
:::

::: warning ข้อควรระวัง
สิ่งที่ผู้ใช้ควรตรวจสอบก่อนทำต่อ
:::

::: danger การดำเนินการถาวร
ใช้เฉพาะเมื่อการทำงานย้อนกลับไม่ได้หรือมีผลกระทบสูง
:::

ตรวจสอบก่อนส่ง Pull Request

npm run docs:build

VitePress จะตรวจลิงก์ภายในระหว่าง build หากพบ dead link ควรแก้ไขก่อน merge