A.9 Maintenance guide — วิธีอัปเดต manual

คู่มือสำหรับคนที่จะอัปเดต manual ต่อจากนี้ — รวมกฎสไตล์ คำต้องห้าม และกระบวนการแก้ไข

ภาพรวมกระบวนการ

1. อ่านกฎสไตล์ (section นี้)
        │
        ▼
2. เขียน/แก้ content
        │
        ▼
3. ตรวจสอบคำต้องห้าม
        │
        ▼
4. อัปเดต sidebar + progress.txt
        │
        ▼
5. build และทดสอบ
        │
        ▼
6. บันทึกใน Changelog (A.8)

1. กฎสไตล์

1.1 ภาษาและน้ำเสียง

เรื่อง	กฎ
ภาษา	ไทย + ทับศัพท์อังกฤษที่ dev ไทยใช้จริง (login, fetch, deploy, cache miss, query, mutation, ...)
น้ำเสียง	senior engineer ที่ทาระบบจริง (Stripe blog + Rust Book) — ไม่ใช่น้ำเสียง academic หรือ AI
มุมมอง	บุคคลที่สาม "โดยทั่วไปจะ..." ไม่ใช่ "ปกติเราจะ..."
ความยาว	แต่ละบทยาวต่างกันได้ตามเนื้อหา — ไม่ใช่ template เดียว

1.2 สิ่งต้องห้าม

ห้าม	เหตุผล
emoji (แม้ใน heading)	ดูไม่เป็นทางการ
mermaid	VitePress compile ช้า + ดูไม่ดีใน markdown raw
:::tip / :::warning callout	ดูเป็น AI cliché
reading-time estimate	ไม่มีประโยชน์จริง
"คุณจะ..." voice	เสมือนสอนผู้อ่าน
┌─┐ box ครอบข้อความไทย	ตัวอักษรไทยไม่ align กับ box
<word> ใน inline code	Vue compiler ตีความเป็น HTML tag → compile error

1.3 สิ่งที่ใช้แทน

แทนที่	ด้วย
mermaid diagram	ASCII tree (├──) หรือ vertical flow (│ ▼) หรือ table
<word> ใน inline code	{word} หรือ [word] (เช่น cache:{name}:{uid} ไม่ใช่ cache:<name>:<uid>)
:::tip	section ปกติพร้อม heading
box รอบข้อความไทย	tree หรือ table

1.4 Scorecard legend

ใช้สัญลักษณ์ + legend ในรูปแบบ markdown list (ไม่พึ่ง CSS เพียงอย่างเดียว):

- 🟢 ดี / ผ่านเกณฑ์
- 🟡 ระดับกลาง / ต้องติดตาม
- 🔴 วิกฤต / ต้องแก้ด่วน

2. คำต้องห้าม/ต้องปรับ

ตารางนี้รวบรวมจาก "lesson learned" ในการ audit ภาษาทั้งระบบ — ห้ามใช้คำใน column "ห้ามใช้" ให้ใช้คำใน column "ใช้แทน"

ห้ามใช้	ใช้แทน
จริง ๆ / จริงๆ	แท้จริงแล้ว / โดยแท้ / ตามจริง
ตรง ๆ / ตรงๆ	โดยตรง
ปกติเราจะ	โดยทั่วไปจะ
ยังไง / ทำงานยังไง	อย่างไร / ทำงานอย่างไร
เป๊ะ	เหมือนกันทุกประการ
เงียบ ๆ / เงียบๆ	อย่างเงียบ
ลอย ๆ / ลอยๆ	ที่ไม่มีบริบท
ผ่าน ๆ / ผ่านๆ	แบบคร่าว ๆ
แปลก ๆ / แปลกๆ	ที่ดูผิดปกติ
เยอะ / เยอะมาก / เยอะสุด	มาก / จำนวนมาก / มากที่สุด
ง่าย ๆ / ง่ายๆ	ง่าย
สั้น ๆ / สั้นๆ	สั้น (เว้นวรรค)
หน้าตาเป็นอย่างไร	โครงสร้างเป็นอย่างไร
memory บวม	memory จะเพิ่มสูง
"vtrc-api น้อง" / "specialty ของ"	หลีกเลี่ยงเปรียบเทียบเป็นบุคคล — ใช้ "โครงสร้างคล้าย ... แต่ขนาดเล็กกว่า" / "จุดเด่นเฉพาะตัว"
เป็นเจ้าของฝั่งเดียว	เป็น service เดียวที่เรียก
catalog (verb)	รวบรวม / ระบุ
leftover (noun)	โค้ดค้างจาก ... / สิ่งที่ค้างอยู่
maintenance burden	ภาระการดูแล
bundle size	ขนาดแพ็กเกจ
production hardening	การเตรียมพร้อมสำหรับ production
Modernization (heading)	การปรับปรุงระบบสมัยใหม่
Mitigating factor	ปัจจัยบรรเทา
Effort (ตาราง)	แรงที่ต้องใช้
Remediation (ตาราง)	การแก้ไข
Impact (ตาราง)	ผลกระทบ
data exfil / exfil channel	ช่องทางดึงข้อมูลออกจากระบบ
forge JWT	ปลอมแปลง JWT
landmine	อันตรายที่ซ่อนรอ
short-circuit	ข้ามกระบวนการทันที
drop-in replacement	สามารถแทนที่ได้โดยตรง
reflect production	ตรงกับสภาพแวดล้อมจริงใน production
active ใน production	ยังไม่ได้รับการแก้ไขใน production
coordinate กับ	ประสานงานกับ
rotate password	เปลี่ยน password
moderate (ขนาด)	ระดับกลาง
"own" (verb)	จุดเดียวที่ / เป็นของ
escape ไป default handler	ผ่านไปยัง default handler
fall through	ผ่านไปยัง
verified โดย	ตรวจสอบโดย
verify caller	ตรวจสอบให้แน่ใจว่า caller คือใคร
reproducible	ทำซ้ำได้ผลลัพธ์เดิม
redaction	การปิดบังข้อมูล
rotation (ของ log)	การหมุนเวียนไฟล์
sync write	เขียนแบบ synchronous

หมายเหตุ — คำเหล่านี้ยังใช้ได้ถ้าอยู่ในเครื่องหมายคำพูดที่ quote จาก user จริง

3. กระบวนการแก้ไข (correction protocol)

เมื่อพบว่า manual มีข้อผิดพลาด:

3.1 ข้อผิดพลาดทางข้อเท็จจริง

กฎสำคัญ: ต้องกลับไปแก้ต้นเหตุทุก volume ที่อ้างถึง ไม่ใช่แค่ flag ใน volume ใหม่

ขั้นตอน:

1. ยืนยันข้อเท็จจริงใหม่ด้วยหลักฐาน (file:line)
2. ค้นหา volume ทั้งหมดที่อ้างถึงข้อความเดิม (ใช้ grep)
3. แก้ทุกไฟล์ที่พบ
4. บันทึกใน A.8 Changelog ตามรูปแบบที่กำหนด

3.2 ข้อจำกัดที่ทราบ (errata)

ถ้าพบสิ่งที่ manual ไม่ครอบคลุม แต่ไม่ใช่ข้อผิดพลาดโดยตรง:

1. เพิ่มใน A.8 Errata ตามรูปแบบ E-01 ถึง E-08
2. ระบุแนวทางแก้ (แม้จะยังไม่ได้ทำ)

3.3 ความเห็นที่เปลี่ยน

ถ้าความเห็นใน manual เปลี่ยน (เช่น เคยแนะนำ X ตอนนี้แนะนำ Y):

1. อย่าลบความเห็นเดิม — เก็บไว้เป็น entry ใหม่ใน Changelog
2. อธิบายเหตุผลที่เปลี่ยน

4. โครงสร้างไฟล์

4.1 การตั้งชื่อไฟล์

ประเภท	รูปแบบ	ตัวอย่าง
index ของ volume	index.md	volume-16-modernization/index.md
บทใน volume	NN-short-name.md	01-principles-strategy.md
โฟลเดอร์ volume	volume-NN-short-name/	volume-16-modernization/

หลักการ:

• NN = เลขบทสองหลัก (01, 02, ..., 12)
• short-name = kebab-case สั้น ๆ สื่อใจ
• ห้ามใช้ภาษาไทยในชื่อไฟล์

4.2 การเพิ่มบทใหม่

เมื่อเพิ่มบทใหม่ใน volume ที่มีอยู่:

1. สร้างไฟล์ NN-short-name.md
2. อัปเดต sidebar ใน docs/.vitepress/config.ts — เพิ่ม entry ใน items ของ volume นั้น
3. อัปเดต docs/progress.txt — เพิ่ม row ในตาราง "Volume X — chapters + status"
4. บันทึกใน A.8 Changelog

4.3 การเพิ่ม volume ใหม่

ถ้า manual ต้องการ volume ใหม่ (เช่น Vol 17):

1. สร้างโฟลเดอร์ docs/volume-17-short-name/
2. สร้าง index.md ในโฟลเดอร์
3. เพิ่ม entry ใน top-level nav ของ docs/.vitepress/config.ts
4. เพิ่ม section ใหม่ใน docs/.vitepress/config.ts สำหรับ sidebar ของ volume
5. อัปเดต docs/progress.txt
6. อัปเดต A.5 cross-reference matrix

5. การ build และทดสอบ

5.1 build บนเครื่อง local

cd /Users/tnd/Documents/I3/vtrc/docs
npm install       # ครั้งแรก
npm run dev       # เปิด http://localhost:5173

5.2 ตรวจสอบก่อน commit

ก่อน commit การเปลี่ยนแปลง ตรวจสอบ:

• [ ] ไม่มี emoji ในไฟล์
• [ ] ไม่มี mermaid
• [ ] ไม่มี :::tip หรือ :::warning
• [ ] ไม่มี <word> ใน inline code
• [ ] ไม่มี ┌─┐ ครอบข้อความไทย
• [ ] ไม่มีคำในตาราง "คำต้องห้าม" (section 2)
• [ ] ทุก claim มี file:line reference
• [ ] sidebar (config.ts) อัปเดต
• [ ] progress.txt อัปเดต
• [ ] ทดสอบใน browser — เปิดหน้าที่แก้และตรวจสอบว่าไม่พัง

5.3 ข้อผิดพลาดที่พบบ่อย

อาการ	สาเหตุ	วิธีแก้
หน้าโหลดเปล่า	Vue compile error — มักจาก {...} ใน markdown	ค้นหา { ในไฟล์ แล้วแทนด้วย [...] หรือ escape
Element is missing end tag	<word> ใน inline code	เปลี่ยนเป็น {word} หรือ [word]
sidebar ไม่อัปเดต	config.ts cache	restart npm run dev
link วิ่งผิด	ใช้ path ผิด — VitePress ใช้ relative path ไม่มี .md	ตรวจ link ใน config.ts

6. หลักฐานและการอ้างถึง

6.1 Source of truth

• docs/audit/01-05 — audit เอกสารต้นฉบับ (เขียนจาก codebase จริง)
• codebase จริงใน /Users/tnd/Documents/I3/vtrc/ — สำหรับ cross-check

6.2 กฎ

• ทุก claim ต้องมี file:line reference
• ถ้า claim มาจาก interview หรือ observation ให้ระบุชัดเจน
• ถ้าไม่แน่ใจ ให้ระบุว่า "ยังไม่ยืนยัน" และเพิ่มใน A.8 Errata

6.3 เมื่อ codebase เปลี่ยน

ถ้า codebase เปลี่ยนหลังจาก manual เขียน:

• ถ้าเป็นแค่ line number ที่เลื่อน — ไม่ต้องแก้ทันที (file:line เป็นจุดอ้างอิงเบื้องต้น)
• ถ้าเป็นการเปลี่ยน behavior — แก้ manual และบันทึกใน Changelog

7. Versioning

manual ไม่มี version number ที่เป็นทางการ — ใช้วันที่ใน Changelog (A.8) เป็นหลักฐานความคืบหน้า

ถ้าต้องการอ้างถึง "manual version" ในการสื่อสารกับทีม ใช้รูปแบบ:

VTRC Knowledge Manual — <YYYY-MM-DD ล่าสุดใน Changelog>

สรุป

manual นี้เป็นเอกสารที่มีชีวิต — ต้องอัปเดตเมื่อ:

1. codebase เปลี่ยน
2. พบข้อผิดพลาด
3. เพิ่มเนื้อหาใหม่

ผู้ดูแลต้องปฏิบัติตามกฎสไตล์ แก้ไขตาม correction protocol และบันทึกการเปลี่ยนแปลงใน Changelog เสมอ