Style Guide — VTRC Knowledge Manual v2

กฎการเขียนของคู่มือเล่มนี้ สืบทอดมาจาก v1 (เอกสารต้นฉบับใน docs-v1-archive/progress.txt) ทุก contributor ต้องปฏิบัติตาม

---

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

• น้ำเสียง — senior engineer ที่ทำระบบจริง (Stripe docs + Rust Book style) ไม่ใช่ marketing
• ภาษา — ไทย + ทับศัพท์อังกฤษที่ dev ไทยใช้จริง (login, fetch, deploy, cache miss, query, mutation, token, session, resolve)
• บุคคลที่สอง — หลีกเลี่ยง "คุณจะ..." ใช้ "ผู้อ่าน..." หรือ passive voice แทน

---

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

ห้าม	เหตุผล
emoji ใน heading	ดูไม่เป็นมืออาชีพ
mermaid ใน body	แทนด้วย ASCII tree (├──) หรือ table — ยกเว้น topology diagrams ใน Vol 2
:::tip / :::warning callout boxes	รบกวนการอ่าน
reading-time estimate	ไม่มีประโยชน์จริง
filler words ("ครอบคลุม", "สมบูรณ์", "ทุกมิติ")	เป็น AI cliché

---

ASCII diagram rules

• ห้ามใช้ ┌─┐ ครอบเนื้อหาไทย — ตัวอักษรไทยทำให้ alignment พัง
• ใช้ tree (├──, └──) หรือ vertical flow (│, ▼)
• ใช้ mermaid ได้เฉพาะ topology diagrams ใน Vol 2 เพราะมีกฎ syntax เฉพาะ (ดู mermaid_syntax)

---

VitePress gotcha — inline code

• ห้ามใช้ <word> ใน inline code (single backtick) — Vue compiler ตีความเป็น HTML tag → compile error "Element is missing end tag"
• ใช้ {word} หรือ [word] แทน เช่น cache:{name}:{uid} ไม่ใช่ cache:<name>:<uid>
• ภายใน fenced code block (```) ใช้ <word> ได้ตามปกติ

---

Scorecard legend

🔴 Critical = active security/data-loss/availability risk
🟡 High     = correctness/maintainability hazard, real impact
🟢 Medium   = friction/hygiene, not yet dangerous

Legend ต้อง render เป็น markdown list (ไม่ใช่ CSS เพียงอย่างเดียว) เพื่อให้ readable ใน raw markdown ด้วย

CSS class สำหรับ scorecard tables: .health-scorecard, .score-summary, .score-legend (ดู .vitepress/theme/custom.css)

---

Citation convention

ทุก claim ต้องมี file:line reference

ตัวอย่างที่ถูก:

cu-central-api ใช้ LDAP สำหรับ authentication (cu-central-api/main-api/src/config.js:20)

ตัวอย่างที่ผิด (ไม่มี citation):

cu-central-api ใช้ LDAP สำหรับ authentication

หากไม่สามารถหา citation ได้ ให้ระบุชัดว่าเป็น hypothesis หรือ TODO

---

Debt ID scheme

Prefix	หมวด
SEC-	Security
PERF-	Performance
CORR-	Correctness / data integrity
LEG-	Legacy / EOL / dependency
QUAL-	Code quality (ใหม่ใน v2)
OBS-	Observability (ใหม่ใน v2)

ID ไหลผ่าน Vol 17 → Vol 20 (debt-ID index) → Vol 19 (modernization wave tasks)

---

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

ตารางสืบทอดจาก v1 progress.txt:317-369 — ใช้คำทางการแทน colloquial:

ห้ามใช้	ใช้แทน
จริง ๆ / จริงๆ	แท้จริงแล้ว / โดยแท้
ตรง ๆ / ตรงๆ	โดยตรง
ปกติเราจะ	โดยทั่วไปจะ
ยังไง	อย่างไร
เป๊ะ	เหมือนกันทุกประการ
เยอะ / เยอะมาก	มาก / จำนวนมาก
catalog (verb)	รวบรวม / ระบุ
leftover	โค้ดค้างจาก ...
Mitigating factor	ปัจจัยบรรเทา
Remediation	การแก้ไข
Impact	ผลกระทบ
active ใน production	ยังไม่ได้รับการแก้ไขใน production
coordinate กับ	ประสานงานกับ

(ตารางเต็มดูใน docs-v1-archive/progress.txt:317-369)

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

---

Audit methodology

ทุก volume ผ่าน docs-verify skill ก่อน mark as done:

1. CORPUS FAIL baseline — full trap-class sweep
2. DELTA — post-remediation
3. CORPUS PASS — final pass
4. RE-AUDIT — independent re-audit

แต่ละ audit report structure: Executive Verdict → Canonical Truths → Findings table → Cross-Document Conflicts → UNVERIFIED Register → Correction Checklist → Coverage & Limitations → Sign-off

ดูตัวอย่างใน docs-v1-archive/audits/