บันทึกการทำ Documentation ด้วย Docusaurus

ในการพัฒนาซอฟต์แวร์นั้น สิ่งหนึ่งที่สำคัญไม่แพ้การเขียนโค้ดก็คือการทำ documentation website ซึ่งจะว่าไปแล้วถ้าจะเริ่มทำกันตั้งแต่ศูนย์มันก็คงจะเหนื่อยเกินไป ไหนจะออกแบบ, เขียนเนื้อหา กว่าจะเสร็จก็ทำกันเหนื่อยพอ ๆ กับเขียนโค้ดเลย

แต่เดี๋ยวนี้มีเครื่องมือที่ช่วยให้เราทำ documentation website ได้ง่ายขึ้น ซึ่งตัวที่น่าสนใจมาก ๆ ตัวหนึ่งเลยก็คือ Docusaurus นั่นเอง เรามาดูกันว่าเจ้าไดโนเสาร์ตัวนี้มันมีดียังไง

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

หน้าตาของโปรเจคเริ่มต้น เปลี่ยนสีเปลี่ยนโลโก้ก็ไม่ต้องแต่งอะไรเพิ่มแล้ว

สำหรับใครที่คิดว่า เอ๊ะ! หน้าตาคุ้น ๆ จัง เราอาจจะเห็นผ่านตามาจากเว็บไซต์ของ React-Native, Jest, Relay นั่นเองครับ

Docusaurus เองก็มาพร้อมกับ development server สำหรับขั้นตอนการพัฒนา รวมไปถึง build script ที่จะแปลงโค้ดทั้งหมดที่เราเขียนให้เป็น static website พร้อมที่จะ deploy ได้เลยครับ

โดยส่วนที่เป็น document และบทความ เราจะใช้ markdown ในการเขียนครับ ซึ่งน่าจะคุ้นเคยกันอยู่แล้ว ส่วนหน้าเพจอื่น ๆ เช่นหน้า home, footer เราสามารถเขียนเป็นโค้ด React ใส่ไปได้เลยครับ

ตัวอย่างหน้าบทความ (เขียนด้วย Markdown)

ตัวอย่างหน้า Home (เขียนด้วย React ได้เลย)

ในความคิดของผมเอง เวลาจะทำ documentation website ผมมักจะนึกถึงสามฟีจเจอร์ที่ควรจะมี คือ versioning, searching และ localization เรามาดูกันว่าเจ้า docusaurus มันทำได้ดีแค่ไหน

Versioning

Docusaurus มี script ที่ใช้ทำ versioning อยู่ในตัวอยู่แล้ว โดยจะสร้างโฟลเดอร์ของ document เก็บไว้ภายใต้เลข version 3 หลัก ทำให้เราสามารถเข้าถึง document ได้ทุก ๆ version

หน้าตาของหน้า versioning

Searching

สำหรับการ search เนื้อหาภายในเว็บไซต์นั้น ตัว docusaurus เองไม่ได้มีฟีจเจอร์นี้ในตัว แต่จะพึ่งบริการของ Algolia DocSearch ได้ โดยการทำงานก็คือ Algolia จะมาเก็บเนื้อหาภายในเว็บของเรา ที่เหลือก็แค่เอา API key ไปใส่ในเว็บ ก็จะสามารถใช้ฟีเจอร์ search ได้ทันที

ถ้าใครอยากดูตัวอย่างก็เข้าไปดูที่นี่ได้ครับ Laravel, React Naitve, Jest

Localization

เรื่องภาษาเองก็ต้องพึ่งบริการของ Crowdin ในการสร้างภาษาอื่น ๆ ภายในเว็บของเรา โดยตัว Crowdin เองสามารถเข้าถึงโค้ดของเราได้ทั้ง Github, Gitlab, Bitbucket ซึ่งเราต้องเข้าไปแปลภาษาอื่น ๆ โดยอ้างอิงจากภาษาหลักของเว็บเรา ถ้านึกภาพไม่ออกดูรูปด้านล่างได้ครับ

แปลภาษาโดยเลือกประโยคจากเนื้อหาทางด้านซ้าย

หน้าที่ใช้ดูว่าเราแปลภาษาไปเท่าไหร่แล้ว

เท่าที่ลองมาใช้งานลำบากพอสมควรครับ ส่วนตัวอยากแก้ที่โค้ดของเรามากกว่าการเข้าไปแก้ในเว็บครับ

คหสต.

สำหรับผมมองว่ามันขึ้นโปรเจคได้ไวมากเพราะมีโครงสร้างให้เรียบร้อย, สามารถ build เว็บเอาไป deploy บน static hosting ได้เลย, ทำ versioning ได้ง่าย, ที่สำคัญ document ของ docusaurus เองอ่านง่ายมาก ๆ เลย

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

ดังนั้นถ้าจะผมมีเว็บที่ต้องการ versioning, search, blog และมีแค่ภาษาเดียว ผมจะเลือกใช้ docusaurus อย่างไม่ต้องคิดเลย

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

aofleejay/express-response-formatter-document