เอกสารระบบแบบภาพ

Visual Documentation ที่ Diagram และคำอธิบายไม่แยกจากกัน

Diagram ที่มีแต่ชื่อกล่องมักตอบไม่ได้ว่าข้อมูลอะไรเข้า เกิดข้อผิดพลาดอย่างไร และใครต้องดูต่อ BranchGuide ให้แต่ละ Node เก็บคำอธิบายเชิงเทคนิค พร้อมหน้า HTML แบบลำดับขั้นที่ค้นหาและอ่านด้วย Screen Reader ได้

สร้างเอกสารระบบแบบภาพ ดูเทมเพลตตัวอย่าง

ภาพรวม API Request Flow 9 Node

เริ่มต้น
Client ส่ง Request
ระบุ Method, Path, Header และ Payload ตามสัญญา
ขั้นตอน
Gateway ตรวจขนาดและรูปแบบ
ปฏิเสธคำขอที่ผิดรูปแบบก่อนเข้าระบบหลัก
ตัดสินใจ
ยืนยันตัวตนและสิทธิ์ผ่านหรือไม่
ตรวจ Credential และ Scope ฝั่ง Server
ขั้นตอน
ประมวลผล Business Rule
ตรวจ Input ซ้ำในขอบเขต Domain
สิ้นสุด
ตอบกลับ 401 หรือ 403
ไม่เปิดเผยรายละเอียดสิทธิ์เกินจำเป็น
ขั้นตอน
อ่านหรือเขียนข้อมูลผ่าน Repository
ควบคุม Transaction และ Timeout
ตัดสินใจ
ประมวลผลสำเร็จหรือไม่
แยกข้อผิดพลาดที่คาดได้จากความล้มเหลวภายใน

และอีก 2 Node ในเทมเพลต

แก้เทมเพลต API Request Flow

สิ่งที่ Flow นี้ช่วยให้เห็น

ออกแบบโครงสร้างก่อนส่งต่อรายละเอียด

ดูเส้นทาง Client, Authorization, Domain และ Repository ทั้งใน Diagram กับรายการข้อความที่อ่านต่อเนื่อง

คำอธิบายไม่ถูกฝังในภาพ

ชื่อ ขั้นตอน การตัดสินใจ และการเชื่อมต่อมี semantic HTML เป็นเนื้อหาหลัก

แยก Overview กับรายละเอียด

Canvas ช่วยเห็นภาพรวม ส่วน Viewer แสดง Markdown ของขั้นปัจจุบันโดยไม่ย่อข้อมูลสำคัญ

ใช้ Template เป็นสัญญาเริ่มต้น

เริ่มจาก API หรือ Authentication Flow แล้วปรับให้ตรงระบบจริงแทนการวาดรูปใหม่ทุกครั้ง

วิธีเริ่มต้น

สร้าง Flow ที่ตรวจทานได้ใน 4 ขั้น

1
กำหนดขอบเขตระบบและผู้ชมเอกสาร
2
วาง Flow หลักโดยไม่ลงรายละเอียด Implementation เกินจำเป็น
3
เติม Input, Output, Failure และเจ้าของใน Markdown ของแต่ละขั้น
4
ให้ผู้พัฒนาและผู้ปฏิบัติงานทบทวน Text Fallback ควบคู่ Diagram

ตัวอย่างเฉพาะหน้า

ตัวอย่าง: เอกสาร Password Reset

บันทึกทั้งเส้นทางผู้ใช้และข้อควรระวังฝั่งระบบโดยไม่ใส่ Secret

1.ผู้ใช้ส่งอีเมล
2.ระบบออก Token แบบใช้ครั้งเดียว
3.ระบบตรวจอายุและสถานะ Token
4.เปลี่ยนรหัสผ่านและยกเลิกเซสชันเดิม

เหมาะกับ

Use case ที่ได้ประโยชน์

Technical Onboarding นักพัฒนา
Runbook ของระบบและ API
เอกสาร Handoff ระหว่าง Product, Engineering และ Support

ขอบเขตที่ควรรู้

ข้อจำกัดก่อนนำไปใช้

BranchGuide ไม่แทนที่ API schema, source code หรือระบบจัดการเอกสารทั้งหมด
เจ้าของระบบต้องอัปเดต Flow เมื่อพฤติกรรม Production เปลี่ยน

เทมเพลตที่เกี่ยวข้อง

ไม่ต้องเริ่มจากหน้าว่าง

API Request Flow

แผนผังคำขอ API ตั้งแต่ Gateway ตรวจรูปแบบและสิทธิ์ ผ่าน Business Logic กับฐานข้อมูล จนสร้าง Response พร้อมเส้นทางปฏิเสธที่สื่อสารได้

ดูเทมเพลต

Flow การ Login และยืนยันตัวตน

แผนผังตรวจข้อมูลเข้าสู่ระบบ แยกผลลัพธ์สำเร็จ บัญชีถูกล็อก และข้อมูลไม่ถูกต้อง เพื่อให้ทีมพัฒนากับทีม Support เห็นเงื่อนไขเดียวกัน

ดูเทมเพลต

Incident Escalation Flow

Flow รับ Alert ประเมินผลกระทบ ตั้งระดับเหตุการณ์ เรียก On-call สื่อสารสถานะ และส่งต่อผู้บัญชาการเหตุการณ์ โดยแยกงานเร่งด่วนกับการติดตามทั่วไป

ดูเทมเพลต

คู่มือที่เกี่ยวข้อง

อ่านหลักคิดก่อนนำ Flow ไปใช้จริง

คู่มือระบบ

วิธีเขียนคู่มือการใช้งานระบบให้คนอ่านเข้าใจและทำตามได้

จัด User Manual ตามงานของผู้ใช้ ระบุสิ่งที่ต้องเตรียม ผลลัพธ์ จุดตัดสินใจ ภาพที่จำเป็น และทางช่วยเหลือเมื่อทำไม่สำเร็จ

อ่านคู่มือ

Markdown และ Mermaid

Markdown Flowchart และ Mermaid ต่างจาก Visual Editor อย่างไร

เปรียบเทียบการเก็บ Diagram เป็นข้อความ Mermaid กับการลากวาง Visual Editor ทั้งเรื่อง Version Control, Layout, เนื้อหาใน Node และการแลกเปลี่ยนไฟล์

อ่านคู่มือ

ตัวอย่าง Flow ระบบ

ตัวอย่าง Flow การ Login และ Reset Password พร้อมกรณีผิดพลาด

แยก Authentication Flow ออกจาก Password Recovery และอธิบายจุดตรวจบัญชี รหัสผ่าน Token เซสชัน และข้อความผิดพลาดที่ปลอดภัย

อ่านคู่มือ

คำถามที่พบบ่อย

คำถามเกี่ยวกับ เอกสารระบบแบบภาพ

Visual Documentation ต่างจากการแนบภาพ Diagram อย่างไร

เนื้อหา BranchGuide ยังเป็น Node, Edge และข้อความที่แก้ ค้นหา และแสดงเป็น HTML ได้ ไม่ถูกแบนรวมเป็นภาพเดียว

ควรใส่รายละเอียดระดับไหนใน Node

ใส่ข้อมูลที่คนทำขั้นนั้นต้องรู้ เช่น Input, ผลลัพธ์, Error และเจ้าของ แล้วลิงก์ไปเอกสารเฉพาะทางแทนการคัดลอกทั้งหมด

API Request Flow แบบมี Text Fallback

สร้างเอกสารระบบแบบภาพ