แนวคิดหลัก
ข้อตกลงเรื่องโฟลเดอร์
docs/
├── index.md # หน้าแรกภาษาจีน
├── guide/ # คู่มือ (แนวคิด การเริ่มต้นใช้งาน)
├── products/ # เอกสารผลิตภัณฑ์
├── changelog.md # บันทึกการเปลี่ยนแปลง
├── en/ # ภาษาอังกฤษ โครงสร้างเหมือนกันทุกประการ
├── th/ # ภาษาไทย โครงสร้างเหมือนกันทุกประการ
└── public/ # รูปภาพและไฟล์สแตติกอื่น ๆกฎสำคัญ: เส้นทางไฟล์ในทั้งสามโฟลเดอร์ภาษาต้องตรงกันแบบหนึ่งต่อหนึ่ง นี่ไม่ใช่แค่เรื่องความเป็นระเบียบ — สคริปต์แปลอัตโนมัติใช้การจับคู่เส้นทางเพื่อตรวจว่าหน้าใดยังไม่มีคำแปล และหน้าใดคำแปลล้าสมัยแล้ว
การแบ่งชั้นเนื้อหา
| ชั้น | คำถามที่ตอบ | รูปแบบการเขียน |
|---|---|---|
| คู่มือ | นี่คืออะไร ทำไมต้องใช้ | เล่าเรื่อง แสดงความเห็นได้ |
| เอกสารผลิตภัณฑ์ | ตั้งค่าอย่างไร พารามิเตอร์มีอะไรบ้าง | ตารางและบล็อกโค้ด แม่นยำไม่กำกวม |
| บันทึกการเปลี่ยนแปลง | เปลี่ยนอะไร กระทบใคร | เรียงจากใหม่ไปเก่า ระบุการเปลี่ยนแปลงที่ทำให้ใช้งานเดิมไม่ได้ |
มาตรฐานการเขียน
front-matter ที่ต้องมี
---
title: ชื่อหน้า # ใช้ในแท็บเบราว์เซอร์และผลการค้นหา
description: สรุปหนึ่งบรรทัด # ใช้สำหรับ SEO และตัวอย่างในการค้นหา
---ความสม่ำเสมอของศัพท์เฉพาะ
แนวคิดเดียวกันต้องใช้คำเดียวกันทั้งเว็บไซต์ โดยแต่ละภาษามีคำแปลที่กำหนดตายตัว อภิธานศัพท์เก็บไว้ที่ scripts/glossary.json และจะถูกบังคับใช้ระหว่างการแปลอัตโนมัติ
กล่องข้อความที่ใช้ได้
เคล็ดลับ
ข้อมูลเสริมและเทคนิคต่าง ๆ
ข้อควรระวัง
ข้อผิดพลาดที่พบบ่อย
อันตราย
การดำเนินการที่ทำให้ข้อมูลสูญหายหรือย้อนกลับไม่ได้
รูปภาพ
เก็บไว้ในโฟลเดอร์ docs/public/ และอ้างอิงด้วยเส้นทางแบบสัมบูรณ์
การตั้งชื่อไฟล์
ใช้ชื่อไฟล์เป็นอักขระ ASCII ล้วน (เช่น arch-overview-v2.png) หลีกเลี่ยงอักขระที่ไม่ใช่ ASCII เพราะ CDN และเบราว์เซอร์บางตัวจัดการไม่สอดคล้องกัน
การจัดการเวอร์ชันและการเปลี่ยนแปลง
การเปลี่ยนแปลงใด ๆ ที่ส่งผลต่อผู้ใช้ต้องบันทึกไว้ในบันทึกการเปลี่ยนแปลง เมื่อฉบับภาษาจีนถูกแก้ไขแต่ฉบับภาษาไทยยังไม่ตาม ระบบตรวจสอบอัตโนมัติจะทำเครื่องหมายว่าหน้านั้นมีคำแปลล้าสมัย