วัฒนธรรมการเขียนเอกสาร Design Docs ของ Google (2020)

• Design docs เป็นหนึ่งในองค์ประกอบสำคัญของวัฒนธรรมวิศวกรรมซอฟต์แวร์ของ Google เป็นเอกสารที่ค่อนข้างไม่เป็นทางการซึ่งผู้เขียนหลักของระบบซอฟต์แวร์หรือแอปพลิเคชันจะจัดทำขึ้นก่อนเริ่มโปรเจ็กต์เขียนโค้ด
  • ใช้บันทึกกลยุทธ์การนำไปใช้งานในระดับสูงและการตัดสินใจด้านการออกแบบที่สำคัญ โดยเน้นเป็นพิเศษที่ trade-off ซึ่งถูกพิจารณาในการตัดสินใจเหล่านั้น
  • งานของวิศวกรซอฟต์แวร์ไม่ใช่การเขียนโค้ด แต่คือการแก้ปัญหา และข้อความแบบไม่เป็นทางการอย่าง Design doc อาจเป็นเครื่องมือแก้ปัญหาที่กระชับและเข้าใจง่ายกว่าโค้ดในช่วงเริ่มต้นของโปรเจ็กต์

บทบาทของ Design docs ในวงจรการพัฒนาซอฟต์แวร์

• นอกเหนือจากการใช้บันทึกการออกแบบซอฟต์แวร์ตามปกติแล้ว ยังทำหน้าที่ดังต่อไปนี้:
  • ระบุประเด็นปัญหาด้านการออกแบบได้ตั้งแต่เนิ่น ๆ ในช่วงที่การเปลี่ยนแปลงยังมีต้นทุนต่ำ
  • ช่วยสร้างฉันทามติเกี่ยวกับการออกแบบภายในองค์กร
  • ช่วยให้มั่นใจว่ามีการพิจารณาประเด็นที่ครอบคลุมหลายส่วนของระบบ (cross-cutting concern)
  • ถ่ายทอดความรู้ของวิศวกรอาวุโสสู่ทั้งองค์กร
  • เป็นพื้นฐานของความทรงจำระดับองค์กรเกี่ยวกับการตัดสินใจด้านการออกแบบ
  • ทำหน้าที่เป็นสรุปผลงานในพอร์ตโฟลิโอทักษะของผู้ออกแบบซอฟต์แวร์

โครงสร้างของ Design doc

• เนื่องจาก Design doc เป็นเอกสารไม่เป็นทางการที่ไม่มีแนวทางด้านเนื้อหาที่เข้มงวด กฎจึงคือให้เขียนในรูปแบบที่เหมาะกับโปรเจ็กต์นั้นมากที่สุด
  • Context and scope: ให้ภาพรวมของภูมิหลังที่มีการสร้างระบบใหม่ขึ้นมา และสิ่งที่จะสร้างจริง
  • Goals and non-goals: ระบุเป้าหมายของระบบและสิ่งที่ไม่ใช่เป้าหมาย
  • The actual design
    • System-context-diagram: ไดอะแกรมที่แสดงให้เห็นว่าระบบเป็นส่วนหนึ่งของสภาพแวดล้อมทางเทคโนโลยีที่ใหญ่กว่าอย่างไร
    • APIs: ภาพร่างของ API ที่ระบบเปิดเผยออกมา
    • Data storage: อภิปรายวิธีการจัดเก็บ/จัดการข้อมูล
    • Code and pseudo-code: ใส่เฉพาะเมื่อใช้เพื่ออธิบายอัลกอริทึมใหม่
    • Degree of constraint: ระดับของข้อจำกัดในพื้นที่ของทางเลือกในการแก้ปัญหาเป็นหนึ่งในปัจจัยหลักที่มีผลต่อรูปแบบของเอกสารการออกแบบ
  • Alternatives considered: ระบุการออกแบบทางเลือกที่สามารถนำไปสู่ผลลัพธ์ใกล้เคียงกันได้อย่างสมเหตุสมผล พร้อมอธิบาย trade-off ของแต่ละแบบและเหตุผลที่เลือกการออกแบบหลัก
  • Cross-cutting concerns: อธิบายว่าประเด็นที่องค์กรให้ความสำคัญร่วมกัน เช่น ความปลอดภัย ความเป็นส่วนตัว และการสังเกตการณ์ระบบ ส่งผลต่อการออกแบบอย่างไร

ควรเขียน Design doc เมื่อใด

• การจะเขียน Design doc หรือไม่นั้นขึ้นอยู่กับว่าประโยชน์จากการสร้างฉันทามติระดับองค์กร การจัดทำเอกสาร และการรีวิวโดยวิศวกรอาวุโส มีมากกว่างานเพิ่มเติมที่เกิดจากการเขียนเอกสารหรือไม่
  • หากไม่ใช่กรณีที่คำตอบของปัญหาด้านการออกแบบยังคลุมเครือเพราะความซับซ้อนของปัญหาหรือของวิธีแก้ การเขียนเอกสารจะมีคุณค่าไม่มากนัก
  • Design doc ที่ใกล้เคียงกับคู่มือการลงมือทำจริงอาจไม่จำเป็น
  • การทำต้นแบบและการวนซ้ำอย่างรวดเร็วอาจไม่เหมาะกับภาระเพิ่มเติมจากการเขียน Design doc

วงจรชีวิตของ Design doc

1. Creation and rapid iteration: เขียนเอกสารและทำซ้ำอย่างรวดเร็วกับเพื่อนร่วมงานเพื่อให้ได้เวอร์ชันที่นิ่ง
2. Review: แชร์ให้ผู้ชมวงกว้างขึ้นเพื่อรับการรีวิว
3. Implementation and iteration: อัปเดตเอกสารเมื่อเกิดการเปลี่ยนแปลงด้านการออกแบบระหว่างการนำไปใช้งานจริง
4. Maintenance and learning: ทำหน้าที่เป็นจุดเริ่มต้นที่เข้าถึงได้ง่ายที่สุดในการทำความเข้าใจระบบ

ความเห็นของ GN⁺

• Design doc เป็นวิธีที่ดีในการสร้างความชัดเจนและหาฉันทามติเมื่อรับมือกับปัญหาที่ยากที่สุดของโปรเจ็กต์ซอฟต์แวร์ที่ซับซ้อน การศึกษาล่วงหน้าช่วยหลีกเลี่ยงการเขียนโค้ดที่ไม่จำเป็นและลดต้นทุนได้ แต่ในขณะเดียวกันก็มีต้นทุนจากเวลาในการเขียนและรีวิวเอกสารด้วย
• ดังนั้นจึงควรตัดสินใจอย่างชาญฉลาดว่าจะเขียน Design doc หรือไม่ให้เหมาะกับแต่ละโปรเจ็กต์ หากมีความไม่แน่นอนในการออกแบบ การมีส่วนร่วมตั้งแต่เนิ่น ๆ ของวิศวกรอาวุโสเป็นประโยชน์ ต้องการฉันทามติระดับองค์กรเกี่ยวกับการออกแบบ ทีมมักมองข้ามประเด็นร่วมอย่างความปลอดภัย หรือจำเป็นต้องมีเอกสารระดับ high-level สำหรับการออกแบบระบบ legacy ก็ควรพิจารณาเขียน Design doc
• นี่เป็นกรณีศึกษาที่แสดงให้เห็นความสำคัญของการทำเอกสารในกระบวนการออกแบบซอฟต์แวร์ได้อย่างดี โดยเฉพาะน่าจะช่วยในการสร้างวัฒนธรรมการออกแบบที่สอดคล้องกันในทีมขนาดใหญ่ อย่างไรก็ตาม เนื่องจากภาระของการทำเอกสารอาจทำให้วิศวกรหลีกเลี่ยง จึงดูสำคัญที่จะต้องมีแนวทางที่กำหนดระดับและขอบเขตอย่างเหมาะสมตามสถานการณ์
• โดยส่วนตัวมองว่า Design doc มีประโยชน์มากในด้าน 1) การพิจารณา trade-off ตามความซับซ้อนของการออกแบบ 2) การค้นพบประเด็นปัญหาด้านการออกแบบได้ตั้งแต่ก่อนลงมือพัฒนา 3) การให้ภาพรวมของระบบเพื่อช่วยให้สมาชิกใหม่เรียนรู้ได้รวดเร็ว เพียงแต่ต้องระวังไม่ให้เอกสารกลายเป็นสิ่งที่เป็นพิธีการเกินไปหรือห่างไกลจากการนำไปใช้งานจริง
• อีกแนวทางหนึ่งอาจเป็นการกำหนดให้ Design doc เป็นข้อบังคับเฉพาะในช่วงเริ่มต้นของโปรเจ็กต์หรือในขั้นตอนการออกแบบที่มีความซับซ้อนสูง พร้อมทั้งให้แรงจูงใจเพื่อให้วิศวกรเขียนโดยสมัครใจ การเน้นว่าการเขียนเอกสารยังช่วยเสริมพอร์ตโฟลิโอทักษะของวิศวกรแต่ละคนได้ด้วยก็น่าจะเป็นเรื่องที่ดี

[GN⁺]

ความคิดเห็นจาก Hacker News

มีความคิดเห็นหลากหลายเกี่ยวกับวัฒนธรรมการเขียนเอกสารออกแบบของ Google:

• การเขียนเอกสารออกแบบกลายเป็นสิ่งที่ทำเพื่อการเลื่อนตำแหน่ง จึงมีแนวโน้มที่จะเขียนโดยคำนึงถึงคณะกรรมการเลื่อนตำแหน่งมากกว่าคนที่สร้างระบบจริง
• ประเภทของเอกสารออกแบบ:
  • เอกสารออกแบบเพื่อการโปรโมต: เน้นว่าตัวโปรเจกต์และบริษัทนั้นยอดเยี่ยมแค่ไหน มากกว่าจุดประสงค์ของโปรเจกต์
  • เอกสารออกแบบแบบเทอร์โบเอนแคปซูเลเตอร์: เต็มไปด้วยศัพท์เฉพาะที่เข้าใจยาก
  • เอกสารออกแบบของพนักงานใหม่: เนื้อหาแทบไม่มี แต่ยาวมาก
  • เอกสารออกแบบที่เต็มไปด้วยข้อเท็จจริงไร้หลักฐาน: อ้างอิงข้อเท็จจริงที่ "ใคร ๆ ก็รู้" แต่จริง ๆ แล้วไม่เคยได้รับการตรวจสอบ
• การออกแบบเป็นส่วนหนึ่งของโปรเจกต์การเขียนโค้ด ดังนั้นการวางแผนทุกอย่างเป็นเอกสารก่อนเริ่มเขียนโค้ดจึงเป็นแนวทางที่ไม่ถูกต้อง
• การเขียนเอกสารล่วงหน้ามักมีแต่เปิดช่องให้คนจับผิดเรื่องเล็กน้อย ขณะที่ปัญหาสำคัญควรแก้ด้วยการสื่อสารกับผู้เกี่ยวข้องล่วงหน้า
• การร่วมกันอัปเดตเอกสารอย่างต่อเนื่องมีประโยชน์มากกว่า
• กำลังคนที่สูญเสียไปกับเอกสารออกแบบมีจำนวนมหาศาล
• วัฒนธรรมเอกสารออกแบบของ Amazon เคยยอดเยี่ยม แต่เมื่อบริษัทอื่นนำวัฒนธรรมแบบ Google ไปใช้กลับกลายเป็นไร้ความหมาย
• มีกรณีที่เดินหน้าโปรเจกต์ไปแล้วโดยไม่ได้รับอนุมัติ แต่กลับมีคนมาให้ฟีดแบ็กกับเอกสารออกแบบในภายหลัง
• เอกสารออกแบบเข้ามาแทนที่เอกสารจริง จนทำให้การทำเอกสารประกอบกลับยิ่งแย่ลง
• เอกสารออกแบบก็มีข้อดีเช่นกัน: ช่วยจัดระเบียบความคิด ค้นหาข้อบกพร่อง ทำให้การสื่อสารราบรื่นขึ้น และช่วยประเมินปริมาณงานได้