การผสานเอกสารและคู่มือรูปแบบ

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

เครื่องมืออย่าง Storybook, Histoire (Vue) และ Ladle จะแสดงผลคอมโพเนนต์แบบแยกส่วนพร้อมเอกสารประกอบ ตัวอย่างจึงสอดคล้องกับโค้ดจริงอยู่เสมอ ไฟล์เอกสารแบบคงที่ (ในวิกิหรือที่เก็บโค้ด) ย่อมคลาดเคลื่อนไปตามเวลา แต่เอกสารที่มีชีวิตจะไม่เป็นเช่นนั้น

สำหรับคอมโพเนนต์ทุกตัว ให้แสดง HTML ขั้นต่ำที่ใช้คอมโพเนนต์นั้น เช่น <app-button variant="primary">Save</app-button> แสดงรูปแบบต่าง ๆ (หลัก รอง อันตราย) สถานะต่าง ๆ (กำลังโหลด ปิดใช้งาน) และกรณีขอบเขต (ข้อความยาว พร้อมไอคอน เต็มความกว้าง) ตัวอย่างที่คัดลอกและวางลงในหน้าจริงได้ตรง ๆ คือสิ่งที่ทีมต่าง ๆ นำไปใช้จริง

เอกสารที่ดีที่สุดจะแสดงผลตัวอย่างไว้ข้างโค้ดต้นฉบับ Storybook รองรับสิ่งนี้โดยตรง ส่วน mdx-deck, Docusaurus และ Astro Starlight รองรับ MDX พร้อม JSX แบบโต้ตอบ การเห็นผลลัพธ์จริงขณะอ่านมาร์กอัปช่วยขจัดความกังวลว่า "ใช้งานได้หรือไม่" ได้ทันที

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

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

จัดทำเอกสารเกี่ยวกับรูปแบบการตั้งชื่อ เช่น BEM, atomic CSS, CSS Modules และการประกอบยูทิลิตีของ Tailwind ระบุกฎสำหรับชื่อคลาส ชื่อพร็อพเพอร์ตีแบบกำหนดเอง และเส้นทางไฟล์อย่างชัดเจน การตั้งชื่อที่สอดคล้องกันช่วยลดภาระทางความคิด ส่วนการตั้งชื่อที่ไม่สอดคล้องกันจะทำให้นักพัฒนาทุกคนเสียเวลาไปตลอด

บันทึกเหตุผลที่ตัดสินใจ ไม่ใช่เพียงผลลัพธ์ของการตัดสินใจ เช่น "เราเลือก React แทน Vue เพราะ…" ช่วยรักษาบริบทไว้ให้ผู้มีส่วนร่วมในอนาคต ADRs (บันทึกการตัดสินใจด้านสถาปัตยกรรม) ในมาร์กดาวน์ที่อยู่ถัดจากโค้ดเป็นรูปแบบน้ำหนักเบาซึ่งยังคงใช้ได้แม้สมาชิกในทีมเปลี่ยนแปลง

สมาชิกใหม่ของทีมควรสามารถส่งมอบคอมโพเนนต์แรกได้ภายในหนึ่งวัน รายการตรวจสอบประกอบด้วย ตั้งค่าที่เก็บโค้ด ติดตั้งสิ่งที่ต้องพึ่งพา เรียกใช้ Storybook ค้นหาแม่แบบคอมโพเนนต์ที่ถูกต้อง เขียนเอกสาร และเปิด PR ให้ติดตามระยะเวลาจนถึง PR แรกเป็นตัวชี้วัด โดยใช้เวลาที่น้อยกว่าเป็นเกณฑ์ที่ดีกว่า

เอกสารที่ดีที่สุดต้องค้นหาได้ง่ายทั้งสำหรับผู้เริ่มค้นหาและผู้มีประสบการณ์ ใช้เว็บไซต์เอกสารที่มีระบบค้นหา (Algolia สำหรับ Docusaurus และระบบค้นหาในตัวสำหรับ Starlight) ติดป้ายกำกับคอมโพเนนต์ด้วยชื่อเรียกพ้องหลายแบบ เช่น ค้นหา "หน้าต่างโมดัล" ได้จากคำว่า "กล่องโต้ตอบ", "ป๊อปอัป" หรือ "ภาพซ้อนทับ"

ใช้เอกสารควบคู่กับการทดสอบการเปลี่ยนแปลงภาพ โดย Chromatic จะบันทึกภาพทุกเรื่องราวของ Storybook ในทุก PR และแสดงความแตกต่างของภาพ PR ที่ผสานแล้วและบังเอิญปรับรูปแบบปุ่มทั่วทั้งเอกสารจะถูกตรวจพบและไม่ผ่านการตรวจสอบ การทำเช่นนี้เป็นการผสานเอกสารเข้ากับการทดสอบระบบการออกแบบอย่างต่อเนื่อง

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

เหตุใดจึงนิยมใช้เอกสารที่มีชีวิต (ซึ่งแสดงผลควบคู่กับโค้ด) มากกว่าไฟล์เอกสารแบบคงที่

เอกสารช่วยเพิ่มคุณค่าของระบบการออกแบบได้ทวีคูณ ใช้เอกสารที่มีชีวิต (Storybook, Histoire, Ladle) ซึ่งนำเข้าโค้ดคอมโพเนนต์จริง แสดงตัวอย่างที่ใช้งานได้ขั้นต่ำ จัดทำเอกสารด้านการเข้าถึง บันทึกการตัดสินใจ เขียนคู่สิ่งที่ควรทำและไม่ควรทำ และใช้ร่วมกับการทดสอบการเปลี่ยนแปลงภาพ ให้ถือว่าเอกสารเป็นผลงานสำคัญ ไม่ใช่สิ่งที่ค่อยทำภายหลัง