เขียน Handover Documentation ที่คนใช้จริง: Runbook, System Map, Owner List

วิธีเขียน handover documentation ที่คนรับช่วงใช้งานได้จริง ด้วย runbook, system map และ owner list พร้อม template ที่เอาไปใช้ส่งมอบระบบได้ทันที

Kasidit Wansudonอ่าน 4 นาที
documentationhandoverrunbookteam-management

เอกสารส่งมอบงานส่วนใหญ่มีชะตากรรมเดียวกัน คือถูกเขียนในสัปดาห์สุดท้ายอย่างรีบเร่ง ยาวหลายสิบหน้า แล้วไม่มีใครเปิดอีกเลย จนวันที่ระบบล่มแล้วพบว่าข้อมูลที่ต้องการไม่อยู่ในนั้น ในแผนงาน 25 สัปดาห์ที่ผมดูแล เฟส knowledge transfer และ handover เป็นส่วนที่ผมให้ความสำคัญที่สุด บทความนี้คือวิธีเขียน handover documentation ที่คนใช้จริง โดยแบ่งเป็นสามชิ้น คือ system map, owner list และ runbook

ทำไม handover documentation ส่วนใหญ่ไม่มีใครใช้

  • เขียนตามโครงสร้างของคนเขียน ไม่ใช่คำถามของคนอ่าน คนรับช่วงไม่ได้อยากรู้ประวัติระบบ เขาอยากรู้ว่า "ถ้า X พัง ต้องทำอะไร"
  • ยาวเกินไป ข้อมูลสำคัญจมอยู่ในย่อหน้าที่ไม่สำคัญ
  • ล้าสมัยตั้งแต่วันที่ส่ง เพราะเขียนจากความจำ ไม่ได้เขียนจากงานที่ทำจริง
  • ไม่เคยถูกทดสอบ ไม่มีใครลองทำตามเอกสารโดยไม่มีคนเขียนช่วย

ชิ้นที่ 1: System map

System map ตอบคำถามว่า "มีอะไรอยู่บ้าง และเชื่อมกันยังไง" ในหน้าเดียว ไม่ต้องสวย แต่ต้องครบ

สิ่งที่ต้องมีต่อระบบ

  • ชื่อระบบ และหน้าที่ในหนึ่งประโยค
  • กลุ่ม user และจำนวนโดยประมาณ
  • stack และเวอร์ชันหลัก
  • อยู่ที่ไหน (ประเภท server, environment) และ deploy ยังไง
  • ระบบอื่นที่มันเรียก และระบบที่เรียกมัน
  • ข้อมูลอะไรที่อ่อนไหว

แผนภาพการเชื่อมต่อช่วยมาก แต่ต้องมีตารางคู่กันเสมอ เพราะตารางค้นหาได้และแก้ง่ายกว่ารูป

ชิ้นที่ 2: Owner list

ปัญหาที่ใหญ่ที่สุดหลังส่งมอบมักไม่ใช่ "ไม่รู้วิธีทำ" แต่คือ "ไม่รู้ว่าต้องถามใคร" owner list แก้ตรงนี้

แยก owner เป็นสามแบบ

  • Business owner คนที่ตัดสินใจว่าระบบควรทำอะไร และอนุมัติการเปลี่ยนแปลง
  • Technical owner คนที่รับผิดชอบ code และ deploy
  • Escalation ถ้า technical owner ไม่ว่าง ติดต่อใคร

ในบล็อกนี้ผมไม่ใส่ชื่อจริงใด ๆ แต่ในเอกสารจริงต้องเป็นชื่อคนและช่องทางติดต่อที่ใช้ได้ ไม่ใช่ชื่อแผนก เพราะ "ทีม IT" ไม่เคยตอบโทรศัพท์ คนต่างหากที่ตอบ

ชิ้นที่ 3: Runbook

Runbook คือหัวใจของ handover มันคือขั้นตอนทีละข้อสำหรับงานที่เกิดซ้ำหรือเหตุการณ์ที่คาดเดาได้ เช่น deploy, rollback, restart service, restore backup, เพิ่ม user, แก้ปัญหาที่เจอบ่อย

หลักการเขียน runbook ที่ใช้ได้

  • หนึ่ง runbook หนึ่งงาน
  • ขึ้นต้นด้วย "ใช้เมื่อไร" เพื่อให้คนอ่านรู้ว่าเปิดถูกอัน
  • ทุกขั้นตอนเป็นคำสั่งที่ copy ไปรันได้ หรือการกระทำที่ชัดเจน
  • มีวิธีตรวจว่าแต่ละขั้นสำเร็จ
  • มีทางถอยถ้าพลาด

วิธีที่ดีที่สุดที่ผมเจอคือเขียน runbook ทุกครั้งที่ทำงานนั้นจริง ไม่ใช่รอเขียนตอนส่งมอบ ผมเล่าวิธีนี้ไว้ใน เปลี่ยนทุก deploy ให้เป็น runbook

Template

นี่คือ template ที่ผมใช้ เก็บเป็นไฟล์ markdown ใน repo ของแต่ละระบบ

# Handover: <system name>

## 1. System summary
- Purpose: <one sentence>
- Users: <group, approx. count>
- Stack: <framework + version, database, queue>
- Environments: <dev / staging / production>
- Depends on: <systems/APIs it calls>
- Used by: <systems that call it>
- Sensitive data: <what, where, how protected>

## 2. Owners
| Role             | Name | Contact | Backup |
|------------------|------|---------|--------|
| Business owner   |      |         |        |
| Technical owner  |      |         |        |
| Escalation       |      |         |        |

## 3. Runbooks
- [Deploy](runbooks/deploy.md)
- [Rollback](runbooks/rollback.md)
- [Restore backup](runbooks/restore.md)
- [Common issues](runbooks/common-issues.md)

## 4. Known issues and risks
| Issue | Impact | Workaround | Planned fix |
|-------|--------|------------|-------------|

## 5. Access checklist
- [ ] Repository access
- [ ] Server / VPN account (personal, not shared)
- [ ] Secrets manager access
- [ ] Monitoring and alert channel

## 6. Verified by
- Receiver performed deploy without help on: <date>
- Receiver performed restore drill on: <date>

ส่วนที่ 6 คือส่วนที่สำคัญที่สุด มันบังคับให้มีการทดสอบเอกสารจริง

ทดสอบเอกสารด้วยการ "ไม่ช่วย"

ก่อนวันส่งมอบ ผมให้คนรับช่วงทำงานจริงจากเอกสารอย่างน้อยสามงาน คือ deploy, rollback และ restore backup โดยผมนั่งดูอย่างเดียว ไม่ตอบคำถาม ทุกครั้งที่เขาติด แปลว่าเอกสารมีช่องโหว่ จดไว้แล้วแก้ทันที

รอบแรกมักติดหลายจุด และนั่นคือเรื่องดี เพราะดีกว่าไปติดตอนตีสองที่ไม่มีใครช่วย

อย่าลืมเรื่อง access

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

รักษาเอกสารให้มีชีวิตหลังส่งมอบ

  • เก็บเอกสารไว้ใน repo เดียวกับ code ไม่ใช่ในไดรฟ์ที่ไม่มีใครหาเจอ
  • กำหนดว่าทุก PR ที่เปลี่ยนวิธี deploy ต้องแก้ runbook ด้วย
  • ใส่วันที่ตรวจล่าสุดไว้ในแต่ละ runbook
  • ลบเอกสารที่ไม่ใช้แล้ว เอกสารผิดอันตรายกว่าไม่มีเอกสาร

สรุป

Handover documentation ที่ดีไม่ใช่เอกสารที่ยาวที่สุด แต่คือเอกสารที่ตอบคำถามของคนรับช่วงได้ตอนเกิดเรื่อง ให้มีสามชิ้น คือ system map ที่เห็นภาพรวมในหน้าเดียว owner list ที่มีชื่อคนจริง และ runbook ที่ copy ไปรันได้ แล้วทดสอบด้วยการให้คนรับช่วงทำงานจริงโดยไม่ช่วย ถ้าเขาทำได้ เอกสารของคุณใช้ได้แล้ว

มีคำถามหรืออยากแลกเปลี่ยน?

ฝากข้อความไว้ที่ guestbook หรือทักมาทาง X ได้เลยครับ