เอกสารส่งมอบงานส่วนใหญ่มีชะตากรรมเดียวกัน คือถูกเขียนในสัปดาห์สุดท้ายอย่างรีบเร่ง ยาวหลายสิบหน้า แล้วไม่มีใครเปิดอีกเลย จนวันที่ระบบล่มแล้วพบว่าข้อมูลที่ต้องการไม่อยู่ในนั้น ในแผนงาน 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 ไปรันได้ แล้วทดสอบด้วยการให้คนรับช่วงทำงานจริงโดยไม่ช่วย ถ้าเขาทำได้ เอกสารของคุณใช้ได้แล้ว