เรื่องนึงที่เพิ่งมาเจอบ่อยๆตอนทำงานจริง คือ การได้ใช้ technical writing

การเขียนให้คนอื่นอ่านรู้เรื่องและสื่อความให้คนฟังเข้าใจระบบที่เราสร้างหรือโค้ดที่เราเขียนได้ดี ถือเป็นทักษะที่ต้องใช้เวลาฝึกฝนค่อนข้างมากและไม่ใช่ทุกคนที่ให้ความสำคัญกับเรื่องนี้

ทักษะการสื่อสารเป็นอีกหนึ่งตัวแปรสำคัญที่บริษัทชั้นนำของโลกต้องการ คุณจะเก่ง algorithm หรือ coding แค่ไหนแต่ถ้าคุณไม่สามารถอธิบายให้เพื่อนร่วมงานเข้าใจสิ่งที่คุณทำหรือปัญหาที่คุณเจอได้ก็ไม่มีประโยชน์ เพราะ การทำงานจริง 100% ต้องทำงานร่วมกับคนอื่น ยิ่งในยุคปัจจุบันที่หลายๆทีมเปลี่ยนไปเป็นทีม remote ที่การสื่อสารส่วนใหญ่เป็นแบบ async การเขียนกลายเป็นอีกหนึ่งทักษะที่จำเป็นสำหรับทีมที่ต้องการทำงานอย่างมีประสิทธิภาพ

คุณคงไม่อยากนั่งใน zoom call ทั้งวันหรอกใช่ไหมล่ะ?

วันนี้ผมอยากแชร์ tips ในการสื่อสารผ่านตัวอักษรว่าทำอย่างไรถึงจะสื่อสารกับคนในทีมได้อย่างมีประสิทธิภาพและลดการใช้การประชุมแบบเห็นหน้า เผื่อให้ทั้งทีมได้โฟกัสกับงานของตัวเองมากยิ่งขึ้นและเพิ่ม productivity โดยรวมของทุกคนครับ

เขียน Technical Document ยังไงให้อ่านรู้เรื่อง

จำได้ว่าสมัยเรียนมหาลัยมีวิชาภาษาอังกฤษตอนปี 1 ที่จับเราเรียนเรื่อง Technical Writing ตอนนั้นเราค่อนข้างดูถูกหัวข้อนี้เอามาก ๆ เพราะเนื้อหาที่เรียนคือการ "อธิบาย" ขั้นตอนของอะไรบางอย่าง ที่ตลกที่สุดคือเขาให้เราเขียน "instruction" ของการต้มมาม่าเป็นภาษาอังกฤษ (ฮา)

กลับมา ณ ปัจจุบัน เราได้ทำงานร่วมกับทีมที่หลากหลาย ทำงานในองค์กรที่เป็น microservice oriented ซึ่งแต่ละทีมก็มี service ที่ตัวเอง maintain หลากหลายตัว มีการทำงาน cross ทีมบ่อยครั้งซึ่งทำให้ documentation มีความสำคัญมาก ซึ่งการเขียน technical documentation เหล่านี้ก็ใช้ concept ของ technical writing ที่เราเคยใช้เขียนวิธีการต้มมาม่านั่นแหละ หลักสำคัญที่เราใช้เวลาเริ่มเขียน documentation มีประมาณนี้

ตั้งกลุ่มเป้าหมายให้ชัดเจน

การเขียน documentation ที่ดีควรใช้เวลาไปกับการ identify กลุ่มเป้าหมายของเราให้มากหน่อย ตัวอย่างของกลุ่มเป้าหมายใน tech company โดยทั่วไปจะมีประมาณนี้

โปรแกรมเมอร์ / software engineer / QA
ตำแหน่ง technical ที่ไม่ได้เป็น engineer (เช่น technical program manager, SA, BA)
data scientists
ตำแหน่งที่ไม่ใช่สายงาน technical

การอธิบายหัวข้อเดียวกันให้คนแต่ละกลุ่มฟังอาจต้องใช้การเขียนคนละรูปแบบ ยกตัวอย่างโดยโปรเจคการนำ Google Cloud's Traffic Director (TD) มาใช้งานในทีม

ตัวอย่างการวิเคราะห์เรื่องกลุ่มเป้าหมายสามารถทำได้คร่าว ๆ ตามนี้

กลุ่มเป้าหมายของโปรเจคนี้คือ

- software engineer คนอื่น ๆ ที่ต้องการนำ TD ไปใช้งาน

กลุ่มเป้าหมายของโปรเจคมีความรู้เชิงลึกเกี่ยวกับ TD ประมาณนี้

- กลุ่มเป้าหมายมีความรู้เกี่ยวกับ service mesh คร่าว ๆ แต่ไม่รู้จัก TD
- กลุ่มเป้าหมายไม่เคยได้ยินเกี่ยวกับ xDS API ที่ TD ใช้ ต้องเขียนอธิบายเพิ่มโดยละเอียด
- กลุ่มเป้าหมายคุ้นเคยกับ Kubernetes เป็นอย่างดี

หลักจากเรา identify กลุ่มเป้าหมายของเราได้แล้ว คำถามถัดไปที่ต้องตอบคือ "แล้วกลุ่มเป้าหมายเราต้องทำอะไรเป็นหลังจากอ่าน document นี้" เราอาจจะลิสออกมาเป็นข้อ ๆ แบบนี้เลยก็ได้

หลังจากอ่านเอกสารนี้จบแล้ว ผู้อ่านต้องสามารถ
- provision TD สำหรับ service ของตัวเองได้
- เชื่อมต่อ service ของตัวเองให้เป็น endpoint บน TD ได้
- config TD ให้ทำหน้าที่เป็น http2 load balancer ได้

หลังจากที่ได้วิเคราะห์กลุ่มเป้าหมายของเราแล้ว ความละเอียด ตัวย่อ และ อีกหลาย ๆ อย่างจะมีจุดอ้างอิงเดียวกันทำให้เราเขียนสื่อสารให้ผู้อ่านเข้าใจได้ตรงจุดและตรงกับองค์ความรู้ของพวกเขามากขึ้นครับ

เขียนให้คนอ่านเข้าใจง่าย

นอกจากวิเคราะห์คนเขียนแล้ว document ที่เขียนก็ควรจะมีความชัดเจนในตัวด้วยโดย:

ให้นิยามกับศัพท์เทคนิค (หรือศัพท์เฉพาะ)
การเขียน document ที่ดี เราควรมองหาศัพท์ที่เป็นศัพท์เทคนิค ศัพท์เฉพาะ หรือ คำยาก ๆ ที่อาจต้องขยายความเพิ่มเติม ยกตัวอย่างจากการเขียน document สำหรับ Traffic Director ผมอาจต้องเขียนคำนิยามสั้น ๆ ของคำว่า "service mesh" ไว้ด้วยเพราะเป็นศัพท์เทคนิค หรือ จะลิ้งไปหาคำอธิบายที่มีอยู่แล้วก็ยิ่งดี และถ้า document ของคุณมีศัพท์ใหม่เยอะ ทำ section glossary (รวมศัพท์) ไว้ก็ใช้ได้เหมือนกัน

อย่าเปลี่ยน term ที่ใช้ไป ๆ มา ๆ
เมื่อเราเรียกของชิ้นนึงด้วยชื่อนึงไปแล้ว เราควรเขียนถึงมันเหมือนเดิมตลอด document ของเรา เช่น Kubernetes ก็ไม่ควรเปลี่ยน term ดื้อ ๆ ระหว่างย่อหน้าเป็น K8s แบบตัวอย่าง:

Service ของเรา deploy ขึ้นบน Kubernetes cluster บลาบลาบลาบลา โดย k8s cluster ของเราใช้บริการของ Google Kubenetes Engine

ถ้าเกิดมันยาวแล้วต้องการใช้คำย่อจริง ๆ เราควร define ไว้ท้ายคำเต็มก่อน เผื่อให้คนอ่านเข้าใจว่ามันสัมพันธ์กันอย่างไร เช่น:

Service ของเรา deploy ขึ้นบน Kubernetes (K8s) cluster บลาบลาบลาบลา โดย K8s cluster ของเราใช้บริการของ Google Kubenetes Engine

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

ถ้าเราต้องการ validate user token ให้ส่ง payload ไปที่ User Validation Service (UVS) แล้วเช็ค response ดูว่า เป็น 200 หรือไม่...

และควรจะยังยึดคำแนะนำข้อก่อนหน้า คือ ถ้าเลือกที่จะใช้ตัวย่อแล้วควรใช้ตัวย่อไปทั้ง document ไม่ควรสลับไปสลับมาระหว่างตัวย่อกับตัวเต็มเพื่อให้อ่านเข้าใจง่าย

ใช้ diagram ช่วย
ข้อมูลบางอย่างต้องใช้กระดาษหลายหน้าในการอธิบายแต่ถ้าเปลี่ยนเป็นแผนภาพ (diagram) แล้วอาจเหลือแค่ภาพภาพเดียว อะไรที่ต้องอธิบายความสัมพันธ์ของสิ่งของการทำออกมาเป็นแผนภาพจะทำให้ผู้อ่านเข้าใจได้ง่ายกว่าการอ่าน document หลาย ๆ หน้า โดยเดี๋ยวนี้มี tool มากมายที่ทำให้สร้าง diagram ออกมาได้ง่าย ๆ และสามารถ collaborate ช่วยกันสร้างออกมาได้ด้วย ตัวอย่างเช่น https://excalidraw.com/ หรือ https://www.lucidchart.com/

ใช้ list ให้เป็น
เรื่องนี้อาจดูเป็นเรื่องเล็ก ๆ แต่หลาย ๆ คนยังใช้ bullet list กับ numbered list ได้ยังไม่ค่อยจะถูกต้อง เรามาดูกันว่า list ทั้งสองแบบควรใช้อย่างไรและใช้ในโอกาสไหนถึงจะสื่อความหมายได้ดี

อย่างแรกเลยคือ bullet list ควรใช้กับ list ที่ไม่ได้มี "ลำดับ" ถึงแม้ว่าจะสลับลำดับสิ่งของใน list ก็ไม่ได้มีผลอะไรต่อสิ่งที่เราเขียน เช่น

Bash provides the following string manipulation mechanisms:

  - deleting a substring from the start of a string
  - reading an entire file into one string variable

สังเกตได้ว่าถึงแม้เราจะสลับลำดับของ bullet ก็ไม่มีผลต่อความหมายของมัน bash ก็ยังทำได้สองอย่างเหมือนเดิม

กลับกันสำหรับ numbered list ควรใช้กับสิ่งที่ต้องทำตามลำดับ เช่น

Take the following steps to reconfigure the server:

  1. Stop the server.
  2. Edit the configuration file.
  3. Restart the server.

จะเห็นได้ว่าลำดับของสิ่งที่ต้องทำมีความสำคัญและไม่สามารถสลับตำแหน่งกันได้ (ไม่งั้น config ก็ไม่อัพเดต)

จริง ๆ จะมี list อีกอย่างนึงซึ่งไม่แนะนำให้ใช้มาก ๆ เรียกว่า embed list หน้าตาจะเป็นประมาณนี้

The booking API enables callers to create booking, query booking, and cancel booking

จะสังเกตได้ว่ามันเป็นลิสที่แอบอยู่ในประโยคธรรมดา ซึ่งมันเป็นทางเลือกที่ไม่ค่อยดีในการสื่อความหมายโดยเฉพาะถ้าเราจะสื่อสารเรื่อง technical

ถ้าเราเจอลิสชนิดนี้ควรเขียนมันออกมาอยู่ในรูปของ bullet list หรือ numbered list ตามสมควร ตัวอย่างเช่น

The booking API enables callers to:

  - create booking
  - query booking
  - cancel booking

หัดเขียน Markdown

Markdown เป็นภาษา markup ที่ใช้เขียน documentation ที่มี formatting ในตัวโดยใช้ text editor อะไรก็ได้ Developer หลาย ๆ คนคงเขียนเป็นอยู่แล้ว ซึ่งมันมีข้อดีคือเราสามารถสร้าง document ที่ format สวย ๆ อ่านง่าย ๆ ได้โดยไม่ต้องเพิ่ง editor อย่าง Microsoft Word หรือ Google Doc.

Markdown ถูกใช้อย่างแพร่หลาย โดยเฉพาะการนำมาเขียน README ของ repo บน Github ซึ่งหลาย ๆ tool ที่เราใช้กันในโลก software development ก็รองรับ markdown เช่นเดียวกัน เช่น Slack เป็นต้น

การใส่ format ให้ตัวอักษรที่เราเขียนทำให้ข้อความที่เราต้องการสื่อมีความหมายมากขึ้นได้อย่างดี ผู้อ่านสามารถใส่หัวข้อ, bullet รวมไปถึง code highlighter ทำให้ตัวอักษรธรรมดามี context มากขึ้นและย่อยง่ายขึ้นสำหรับผู้อ่าน

สำหรับคนที่สนใจเริ่มหัดเขียน Markdown หรืออยากรื้อฟื้นสกิลสามารถลองเล่นได้ที่นี่เลยครับ

https://www.markdowntutorial.com/

อย่างที่ผมได้บอกไว้ตอนต้นว่าทักษะการสื่อสารผ่านการเขียนสำคัญมากในการทำงานยุคปัจจุบัน หวังว่าบทความนี้จะมีประโยชน์กับผู้อ่านไม่มากก็น้อยครับ

ถ้ามีหัวข้อที่สนใจหรืออยากให้เขียนถึง หรือ แค่อยากแลกเปลี่ยนไอเดียสามารถส่งข้อความมาหาผมทาง Twitter @V_TNO ได้เลยครับ