คู่มือผู้เขียนบทเรียน

คู่มือนี้สำหรับทุกคนที่เขียนหรือแก้บทเรียนใน TESA Open Knowledge ไม่ว่าจะเป็นอาจารย์ วิศวกร หรือผู้เรียนที่อยากช่วยปรับเนื้อหา อ่านรอบเดียวให้จบก่อนเริ่ม แล้วเปิดค้างไว้ระหว่างเขียน ขั้นตอนส่งงาน (fork, DCO, pull request) อยู่ใน CONTRIBUTING.md

แม่แบบที่ใช้คู่กับคู่มือนี้

แม่แบบ	ใช้ทำอะไร
course/	หลักสูตรใหม่: course.yaml, README.md, README.en.md, credits.yaml
module/README.md	หน้าโมดูล
lesson/	บทเรียน: README.md, README.en.md, quiz.yaml, slides.md และตัวอย่างไฟล์ examples/ practice/ solution/

1. หน่วยการเรียนรู้

หน่วย	ขนาด	หมายเหตุ
เส้นทาง (pathway)	หลายหลักสูตร	นิยามใน catalog/tracks.yaml ไม่ใช่โฟลเดอร์
หลักสูตร (course)	8–30 ชั่วโมง	อยู่ในระดับเดียว มี capstone
โมดูล (module)	2–6 ชั่วโมง	สร้างความสามารถหนึ่งอย่าง ปิดด้วย checkpoint
บทเรียน (lesson)	30–60 นาที (front matter ยอมรับ 20–75)	หน่วยที่ติด skill ID แบ่งเป็นช่วงกิจกรรมช่วงละไม่เกิน 6–10 นาที

ID ของบทเรียนมีรูปแบบ <short>.mNN.lNN เช่น aiot-mpy.m02.l03 โดย <short> มาจาก catalog/courses.yaml ID ถาวร เมื่อ merge แล้วห้ามเปลี่ยนและห้ามนำกลับมาใช้ซ้ำ เพราะใบรับรองและลิงก์ของทักษะอ้างถึง ID นี้ ตัวเลขในชื่อโฟลเดอร์มีไว้เรียงลำดับเท่านั้น

2. กติกาเรื่องคำ

• เรียกหน่วยการเรียนรู้ว่า บทเรียน โมดูล หลักสูตร ในหลักสูตร AIoT in Action ใช้คำว่า “ตอน” แทนโมดูลได้ถ้าจำเป็น
• ห้ามใช้ คาบ หรือ คาบเรียน ในความหมายของช่วงเวลาเรียน และห้ามเรียกหน่วยการเรียนรู้ว่า session N
• คาบ ในความหมายของคาบของสัญญาณถูกต้อง ให้เขียนว่า คาบเวลา เช่น “คาบเวลาของ PWM เท่ากับ 20 ms”
• เรียกผู้อ่านว่า ผู้เรียน และตัดกรอบของชั้นเรียนมหาวิทยาลัยออก เช่น การระบุคณะหรือมหาวิทยาลัยของผู้เรียน สัดส่วนคะแนน คำเรียกแบบรุ่นพี่รุ่นน้อง และการบังคับจำนวนคนต่อกลุ่ม (บอกได้ว่า “ถ้าบอร์ดมีไม่พอ ทำเป็นกลุ่มได้” แต่ไม่ใช่ข้อบังคับ)
• ศัพท์ที่ใช้บ่อยอยู่ใน glossary/terms.yaml เขียนคำไทยคู่คำอังกฤษในวงเล็บครั้งแรกที่ใช้ เช่น อินเทอร์รัปต์ (interrupt)

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

• ภาษาไทยเป็นต้นฉบับ ใช้ศัพท์เทคนิคภาษาอังกฤษได้ ชื่อตัวแปร ฟังก์ชัน และไฟล์เป็นภาษาอังกฤษ
• เขียนเหมือนโค้ชที่อบอุ่นและแม่นยำ คุยกับผู้เรียนตัวต่อตัว ใช้ “เรา” เมื่อทำด้วยกัน และ “คุณ” เมื่อชวนผู้เรียนลงมือ
• บอกว่า ทำไม ไม่ใช่แค่ทำอะไร
• ให้กำลังใจแบบจริงใจ ไม่เว่อร์ เช่น “ลองดูก่อน ถ้าติดเดี๋ยวเราค่อย ๆ แกะด้วยกัน” ไม่ใช่ “สุดยอด!!!”
• ไม่ใช้ emoji ตกแต่ง ในหัวข้อ เนื้อหา หรือคอมเมนต์ ใช้หัวข้อธรรมดาหรือตัวหนาแทน
• หลีกเลี่ยงประโยคแม่แบบซ้ำ ๆ เช่น “ในส่วนนี้เราจะ…” หรือ “มาดูกันว่า…” ใช้เครื่องหมายขีดยาว (—) เท่าที่จำเป็น และผสมร้อยแก้วกับรายการตามที่พูดจริง
• ทดสอบง่าย ๆ: อ่านหน้าที่เขียนแล้วถามตัวเองว่า “นี่เหมือนครูคนหนึ่งเขียนให้ลูกศิษย์ไหม”

4. ความปลอดภัยและข้อมูลภายใน

• ห้ามมีข้อมูลลับจริง ทั้งรหัส Wi-Fi, token, รหัสผ่าน broker, กุญแจ และใบรับรองที่มีกุญแจ ในโค้ด ภาพหน้าจอ และ log ใช้ค่าตัวแทนเสมอ เช่น WIFI_PASSWORD = "<your-password>"
• ก่อนส่ง ค้นไฟล์ของคุณด้วยคำว่า PASSWORD, SECRET, TOKEN, API_KEY แล้วดูว่าทุกค่าเป็นค่าตัวแทน
• ห้ามใส่ path ภายในเครื่องหรือเซิร์ฟเวอร์ ชื่อเครื่อง หรือลิงก์ไปยังเอกสารภายในของหน่วยงานใด
• ใช้โดเมน tesaiot.dev เท่านั้น: BENTO IDE https://ide.tesaiot.dev/ · Developer Hub https://dev.tesaiot.dev/
• บทเรียนที่ต้องใช้ใบรับรองหรือกุญแจ ให้สอนวิธีสร้างหรือขอเอง ไม่แจกไฟล์ที่ใช้งานได้จริง รายละเอียดใน SECURITY.md

5. สัญญาอนุญาตและเครดิต

สิ่งที่คุณเขียน	สัญญาอนุญาต
เนื้อหา Markdown สไลด์ และภาพที่ทำเอง	CC BY-NC 4.0
แม่แบบในโฟลเดอร์ resources/	CC BY 4.0
โค้ดใหม่	Apache-2.0 (ใส่ SPDX header ทุกไฟล์)
โค้ดที่นำเข้าจากหลักสูตร AIoT in Action ของ AIC	คง MIT และบรรทัดลิขสิทธิ์เดิม
ภาพหรือไฟล์ของบุคคลที่สาม	ตามต้นทาง ต้องลงใน credits.yaml

• เครดิต TESA ต้องอยู่ทุกชั้น ทุก slides.md มี footer: เป็นบรรทัดเครดิตสั้น และทุก README.md / README.en.md ของหลักสูตร จบด้วยหัวข้อ “อ้างอิง TESA / How to cite TESA” ที่มีข้อความเครดิตเต็มของหลักสูตรนั้น แม่แบบใส่ไว้ให้แล้ว อย่าลบ รายละเอียดใน ATTRIBUTION.md
• เนื้อหาที่นำเข้าจากงานอื่น ใส่เครดิตต้นทางใน README ของหลักสูตรและใน course.yaml (authors, source) เช่น
  • หลักสูตร AIoT: “ดัดแปลงจาก AIoT in Action — Embedded Systems for AIoT Developer, © 2026 รศ.วิรุฬห์ ศรีบริรักษ์ วิศวกรรมระบบสมองกลฝังตัว ภาควิชาวิศวกรรมไฟฟ้า คณะวิศวกรรมศาสตร์ มหาวิทยาลัยบูรพา (BUU) · Advance Innovation Centre (AIC) · BENTO & TESAIoT (CC BY 4.0 / MIT)”
  • หลักสูตร C1–C3: “เนื้อหาต้นฉบับโดย ผศ.ดร.สันติ นุราช ภาควิชาวิศวกรรมระบบควบคุมและเครื่องมือวัด คณะวิศวกรรมศาสตร์ มหาวิทยาลัยเทคโนโลยีพระจอมเกล้าธนบุรี (KMUTT) (https://github.com/drsanti) ภายใต้การสนับสนุนของสมาคม TESA”
• โค้ดของ Infineon ลิงก์ไปยัง repository และ tag เป็นค่าเริ่มต้น ถ้าจำเป็นต้องคัดลอก ต้องคง header และไฟล์สัญญาอนุญาตเดิม และอ้างอิงแหล่งให้ครบ
• แผนที่ทักษะ เป็น CC BY-SA 4.0 อย่าคัดลอกข้อความหรือรายการแหล่งเรียนรู้ของ Embedded Systems Engineering Roadmap ลงในบทเรียน ให้ลิงก์ไปแทน
• เขียนชื่อ Infineon®, PSOC™, ModusToolbox™, OPTIGA™ ให้ถูก และใส่สัญลักษณ์ครั้งแรกในแต่ละหน้า ดู TRADEMARKS.md

6. หลักฐานก่อนคำอ้าง

• ทุกไฟล์ใน examples/, practice/, solution/ ที่บทเรียนอ้าง ต้องมีอยู่จริง และทุกภาพที่ Markdown หรือสไลด์อ้าง ต้องมีอยู่จริง
• ห้ามแต่ง API ขึ้นเอง ข้อเท็จจริงเรื่อง API ของ MicroPython ต้องมาจากโค้ดที่รันได้จริงบนเฟิร์มแวร์ที่บทเรียนระบุ ส่วนภาษา C อ้างอิง SDK สาธารณะ tesaiot-pse84-devkit-sdk
• รันโค้ดทุกไฟล์บนบอร์ดจริงหรือ BENTO Emulator ก่อนส่ง และจดชื่อบอร์ด เวอร์ชันเฟิร์มแวร์ และเวอร์ชัน toolchain หรือ emulator ไว้ใน PR การตรวจ syntax อย่างเดียว (เช่น mpy-cross) ไม่นับเป็นการทดสอบบนบอร์ด
• ไฟล์หนึ่งไฟล์ไม่เกิน 5 MB ใช้ภาพ PNG JPG หรือ SVG และไม่เพิ่มไฟล์วิดีโอ

7. โครงโฟลเดอร์

courses/<course-id>/
  course.yaml            ข้อมูลหลักสูตร
  README.md              หน้าหลักสูตรภาษาไทย (จบด้วย "อ้างอิง TESA / How to cite TESA")
  README.en.md           หน้าหลักสูตรภาษาอังกฤษ
  credits.yaml           เครดิตภาพ (ถ้าไม่มีภาพบุคคลที่สาม ใช้ images: [])
  assets/                ภาพที่ใช้ร่วมกันทั้งหลักสูตร (ไม่บังคับ)
  shared/                โค้ดที่หลายบทเรียนใช้ร่วมกัน (ไม่บังคับ)
  mNN-<slug>/            โมดูล (slug เป็นตัวพิมพ์เล็ก ASCII คั่นด้วย -)
    README.md            หน้าโมดูล: เป้าหมาย รายการบทเรียน checkpoint
    lNN-<slug>/          บทเรียน
      README.md          หน้าบทเรียนภาษาไทย พร้อม front matter
      README.en.md       ฉบับภาษาอังกฤษ (ไม่บังคับ)
      slides.md          สไลด์ Marp (ไม่บังคับ)
      examples/ practice/ solution/   โค้ด (practice กับ solution จับคู่กันด้วยชื่อไฟล์เดียวกัน)
      lab.md             แล็บ (ไม่บังคับ)
      quiz.yaml          เช็กความเข้าใจ (ไม่บังคับ แต่ควรมี)
      instructor-notes.md บันทึกสำหรับผู้สอน เปิดสาธารณะ ห้ามมีคำตอบของข้อสอบจริง
      resources/         cheatsheet หรือ checklist (Markdown)
      img/               ภาพของบทเรียน

ใช้ path แบบสัมพัทธ์ (relative) เสมอ

8. course.yaml

แม่แบบ: course/course.yaml

ฟิลด์	กติกา
id, short	ต้องตรงกับที่ลงทะเบียนใน catalog/courses.yaml และ id ตรงกับชื่อโฟลเดอร์
title, summary	มีทั้ง th และ en summary ยาว 1–3 ประโยค
level	L1–L5 ดู tqp/levels.md
status	pre-alpha / alpha / beta / stable เกณฑ์อยู่ใน GOVERNANCE.md
audience	เลือกจาก public, student, developer, entrepreneur, educator
hours	ชั่วโมงเรียนรวมโดยประมาณ
hardware	emulator: true ถ้าเรียนใน BENTO Emulator ได้โดยไม่มีบอร์ด · boards เลือกจาก eva-kit, devkit, none
toolchain	เวอร์ชันที่ใช้ทดสอบ เช่น bento-firmware, micropython, modustoolbox
prerequisites	courses (id ของหลักสูตร) และ skills ({skill, level})
outcomes	ผลลัพธ์การเรียนรู้ระดับหลักสูตร กริยาที่วัดผลได้
authors	{name, url, role} โดย role เป็น author, adapter หรือ reviewer
sponsors	[TESA]
license	content: CC-BY-NC-4.0 และ code: Apache-2.0 (หรือ MIT สำหรับโค้ดที่นำเข้าจาก AIC หรือ none)
source	เฉพาะเนื้อหาที่นำเข้า: repo, ref (commit), note
modules	{id, title} โดย id ตรงกับชื่อโฟลเดอร์โมดูล

9. front matter ของบทเรียน

แม่แบบ: lesson/README.md ฉบับอังกฤษใช้ front matter ชุดเดียวกันแต่ lang: en

ฟิลด์	กติกา
id	<short>.mNN.lNN ถาวร
lang	th ในไฟล์ไทย en ในไฟล์อังกฤษ
title, summary	th และ en summary หนึ่งประโยค
level	L1–L5
time_min	จำนวนเต็มใน concept, practise, lab, check ใส่เฉพาะที่มี รวม 20–75 นาที
hardware	{emulator: true/false, boards: [...]}
prerequisites	lesson id ของบทก่อนหน้า (ว่างได้)
objectives	2–4 ข้อ แต่ละข้อมี th และ en เขียนด้วยกริยาที่วัดผลได้ + เงื่อนไข (+ เกณฑ์)
develops	อย่างน้อย 1 รายการ {skill, to} skill ID ต้องมีใน skills/skills.yaml และ to เป็น 1–5
assesses	ไม่บังคับ {skill, level, evidence} โดย evidence ชี้ไฟล์ในบทเรียน
context	อิสระ เช่น {platform: psoc-edge-e84, lang: micropython, ide: bento-ide} ชื่อผู้ผลิตและเครื่องมืออยู่ที่นี่ ไม่อยู่ใน skill ID
status	วงจรชีวิตของบทเรียนนี้
translation	done หรือ pending (สถานะของ README.en.md)
slides	path ของสไลด์ ถ้ามี
source	ที่มาของเนื้อหาที่นำเข้า ถ้ามี
source_sha256	เฉพาะไฟล์อังกฤษ: ค่าจาก python3 tools/i18n_stale.py --hash <โฟลเดอร์บทเรียน>/README.md

เขียนเป้าหมายให้วัดผลได้ “อธิบาย…” อย่างเดียวยังวัดไม่ได้ ให้บอกเงื่อนไขและเกณฑ์ เช่น “เขียนโปรแกรมอ่านปุ่มแบบกันเด้งบน BENTO Emulator ให้กดหนึ่งครั้งนับหนึ่งครั้ง ทดสอบกด 10 ครั้งนับได้ 10”

ถ้าต้องการทักษะที่ยังไม่มีใน skills.yaml อย่าตั้ง ID เอง ให้ใช้ ID ที่ใกล้ที่สุดไปก่อน แล้วเปิด issue เสนอทักษะใหม่

10. เนื้อหาบทเรียน

หัวข้อในไฟล์ไทยเรียงตามลำดับนี้ ข้ามหัวข้อที่ไม่มีเนื้อหาได้ แต่ห้ามสลับลำดับ

หัวข้อ	ใส่อะไร
## เป้าหมาย	เป้าหมายชุดเดียวกับ front matter และเวลาโดยประมาณ
## ก่อนเริ่ม	คำถามทวนบทก่อน 2 ข้อ
## ดูของจริงก่อน	รันงานที่เสร็จแล้ว ให้ผู้เรียนทายก่อนรัน ผู้เรียนต้องเห็นผลที่ทำงานได้ภายใน 15 นาทีแรก
## แนวคิด	ไม่เกิน 3 ช่วง ช่วงละไม่เกิน 6 นาทีหรือหนึ่งหน้าจอ
## ตัวอย่างสมบูรณ์	ตัวอย่างที่รันได้ พร้อมป้ายขั้นตอน ท่าที่ 1, 2, 3
## ฝึกเติม	ไฟล์ใน practice/ ที่มีช่องว่างให้เติม
## เฉลย	ไฟล์ใน solution/ คอมเมนต์อธิบายว่าทำไม และบอกให้ลองเองก่อนอย่างน้อย 15 นาที
## เช็กความเข้าใจ	3–5 ข้อใน quiz.yaml ตอบถูกตั้งแต่ 80% ขึ้นไปถือว่าจบบทเรียน
## แล็บ	งานบนบอร์ดหรือ emulator และหลักฐานที่ต้องเก็บ (รูป log วิดีโอ) ไว้ใน portfolio
## ไปต่อ	โจทย์ท้าทาย datasheet หรือกรณีใช้งานจริง
## สะท้อนคิด	คำถามให้ผู้เรียนคิดทบทวน

ลิงก์ไปยังโค้ดด้วย path สัมพัทธ์ เช่น [examples/02_led_blink.py](examples/02_led_blink.py)

กติกาการสอน

1. ทุกเป้าหมายมีข้อเช็กคู่กัน เป้าหมายที่ไม่มีข้อเช็ก ไม่ผ่านการตรวจด้านการสอน
2. ตัวช่วยค่อย ๆ ลดลง บทแรกของโมดูลเว้นว่างราว 2 จุด บทต่อไปเว้นมากขึ้น จนงาน checkpoint หรือ capstone เป็นไฟล์เกือบเปล่า
3. ลำดับ Predict → Run → Investigate → Modify → Make ทายก่อนรัน รัน สำรวจว่าทำไม ลองแก้ แล้วสร้างเอง ใช้ตามความเหมาะสมของเนื้อหา
4. ตัวอย่างมีป้ายขั้นตอน ใช้ “ท่าที่ 1, 2, 3” ในตัวอย่างสมบูรณ์ทุกตัว
5. ใช้ emulator กับแนวคิด ใช้บอร์ดจริงกับการดีบักและการวัด ถ้าบทเรียนทำได้ทั้งสองแบบ ให้บอกจุดที่ต่างกันให้ชัด
6. เช็กย้อนหลัง ใส่ข้อเช็กจากบทก่อน ๆ 1–2 ข้อ เพื่อทบทวนแบบเว้นระยะ

บันทึกสำหรับผู้สอน (เวลา จุดที่ผู้เรียนมักติด ความต่างระหว่างบอร์ดกับ emulator) แยกไว้ใน instructor-notes.md ไฟล์นี้เปิดสาธารณะ จึงห้ามมีคำตอบของข้อสอบจริง

11. quiz.yaml

แม่แบบ: lesson/quiz.yaml

• แต่ละข้อมี id, objective (ลำดับของเป้าหมายเริ่มที่ 1), type, prompt
• type: single เลือกหนึ่งข้อ · multi เลือกหลายข้อ · order เรียงโค้ด (Parsons) · short ตอบสั้น
• choices จำเป็นสำหรับ single, multi, order และ answer เป็นลำดับของตัวเลือกเริ่มที่ 0 สำหรับ order คือลำดับที่ถูก สำหรับ short ใส่คำตอบที่ยอมรับเป็นข้อความ
• ใส่ explain ทุกข้อ อธิบายว่าทำไมคำตอบนั้นถูก
• ข้อในนี้เป็นสื่อการเรียน ไม่ใช่ข้อสอบจริงของ TQP

12. credits.yaml

แม่แบบ: course/credits.yaml

• ทุกภาพที่ไม่ได้ทำเองต้องมีหนึ่งรายการ: path (สัมพัทธ์กับโฟลเดอร์หลักสูตร), title, author, source, license, modified
• license เป็น SPDX ID (เช่น CC-BY-SA-4.0), Infineon-permission หรือ own
• ภาพ CC BY-SA ที่แก้ไข (เช่น ใส่คำไทย) กลายเป็น CC BY-SA ใส่ modified: true
• ภาพที่ไม่มีสัญญาอนุญาตชัดเจน ห้ามใช้
• ทุกภาพในบทเรียนและสไลด์ต้องมีข้อความ alt ที่บอกว่าภาพแสดงอะไร

13. สไลด์ (Marp)

แม่แบบ: lesson/slides.md

• front matter ต้องมี marp: true และ lang: th (หรือ en)
• ต้องมี footer: "TESA Open Knowledge · © 2026 สมาคมสมองกลฝังตัวไทย (TESA) · CC BY-NC 4.0" ถ้ามี footer ของตัวเองอยู่แล้ว ให้รวมเข้าด้วยกัน โดยคงบรรทัดเครดิตนี้ไว้
• สไลด์เป็นสื่อประกอบ ส่วน README.md ของบทเรียนต้องอ่านได้ครบโดยไม่ต้องเปิดสไลด์
• หน้าสุดท้ายใส่ข้อความเครดิตเต็มและเครดิตภาพจากบุคคลที่สาม

วิดีโอประกอบ (YouTube)

วิดีโอไม่ได้ฝังไว้ใน README แต่ลงทะเบียนไว้ที่เดียวใน catalog/videos.yaml แล้วเว็บจะแสดงกล่อง “วิดีโอประกอบ” ให้เองทั้งหน้าไทยและหน้าอังกฤษ บนหน้าบทเรียนกล่องนี้อยู่ด้านบน บนหน้าหลักสูตรจะรวมวิดีโอของทุกบทเรียนไว้ท้ายหน้า

• เพิ่มรายการใน videos: ประกอบด้วย id (11 ตัวอักษรจาก URL ของ YouTube), title ตามที่เผยแพร่จริง, channel (ต้องมีใน channels:) และ lessons เป็นรายการ id ของบทเรียนที่วิดีโอนี้ประกอบ
• ช่องใหม่ต้องมีชื่อสองภาษา ถ้าเป็นผลงานของบุคคล ให้ใส่ credit เป็นเครดิตเต็มพร้อมสังกัด (ดู ATTRIBUTION.md)
• ลิงก์ไปที่ YouTube เท่านั้น ไม่คัดลอกไฟล์วิดีโอหรือภาพปกเข้ามาใน repo
• tools/validate.py ตรวจว่าทุก id ของบทเรียน ช่อง และ playlist มีอยู่จริง

14. ฉบับภาษาอังกฤษ

• วาง README.en.md ไว้ข้าง README.md ในโฟลเดอร์เดียวกัน front matter ชุดเดียวกัน แต่ lang: en
• เมื่อแปลเสร็จ ใส่ source_sha256 ในไฟล์อังกฤษ และตั้ง translation: done ในทั้งสองไฟล์
• ถ้าแก้ฉบับไทยจนสาระเปลี่ยน ให้แก้ฉบับอังกฤษด้วย หรือตั้ง translation: pending
• ร่างจากเครื่องแปลใช้ได้ ถ้ามีคนตรวจทานและบอกไว้ใน PR

15. เช็กลิสต์ก่อนส่ง

• python3 tools/validate.py ผ่าน
• รันโค้ดทุกไฟล์บนบอร์ดหรือ emulator แล้ว และจดเวอร์ชันไว้สำหรับ PR
• ทุกเป้าหมายมีข้อเช็กใน quiz.yaml
• skill ID ทุกตัวมีใน skills/skills.yaml
• ไม่มีข้อมูลลับ path ภายใน หรือโดเมนเก่า
• ใช้คำตามกติกา และไม่มี emoji ตกแต่ง
• ภาพใหม่ทุกภาพมี alt และอยู่ใน credits.yaml ถ้าไม่ได้ทำเอง
• สไลด์มี lang และ footer เครดิต TESA และ README ของหลักสูตรจบด้วย “อ้างอิง TESA / How to cite TESA”
• สถานะ translation ถูกต้อง
• ทุก commit มี DCO sign-off (git commit -s)