สร้างเอกสารผลิตภัณฑ์สวยงาม ไม่ต้องเขียนโค้ด

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

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

ในการสร้างเอกสารผลิตภัณฑ์ ทีมงานมักจะใช้เครื่องมือจัดทำเอกสารสำเร็จรูป เช่น Notion หรือเครื่องมือจัดการเนื้อหา เช่น Confluence และ CMS หรือเครื่องมือสร้างเอกสาร เช่น Docusaurus และ Gitbook อย่างไรก็ตาม โซลูชันเหล่านี้มักจะพบปัญหาดังต่อไปนี้:

1. **การจัดทำเอกสารต้องใช้การเขียนโค้ด** ซึ่งมีค่าใช้จ่ายสูง แม้หลังจากเขียนเอกสารเสร็จแล้ว ประสบการณ์การอ่านจริงก็มักจะไม่เป็นไปตามที่คาดหวัง
2. **การจัดทำเอกสารเกี่ยวข้องกับการทำงานร่วมกันของหลายบทบาท** ทำให้การจัดการเวอร์ชันทำได้ยาก และทำให้ยากต่อการสื่อสารข้อเสนอแนะในการปรับปรุงให้ผู้อื่นทราบ
3. **การเผยแพร่เอกสารที่เสร็จสมบูรณ์ไปยังสภาพแวดล้อมการใช้งานจริง (production) นั้นง่ายเกินไปหรือซับซ้อนเกินไป** ซึ่งอาจเกี่ยวข้องกับกระบวนการทางวิศวกรรมที่ยากสำหรับเพื่อนร่วมงานที่ไม่ใช่สายเทคนิคในการจัดการ นำไปสู่ข้อผิดพลาด

ทีม Apidog เคยใช้ Docusaurus ในการสร้างเอกสารของเรา เมื่อเอกสารของเรามีการพัฒนาและปรับปรุงอย่างต่อเนื่อง เราก็พบปัญหาบางอย่างที่กล่าวมาข้างต้นเช่นกัน หลังจากสรุปประสบการณ์และบทเรียนที่ได้รับ เราได้พัฒนาโซลูชันและรวมเข้ากับ Apidog ตอนนี้ **เอกสารผลิตภัณฑ์ของทีม Apidog ได้ย้ายมายัง Apidog ทั้งหมดแล้ว โดยการสร้างและการนำเสนอทั้งหมดจัดการโดย Apidog**

ฉันจะแบ่งปันแนวปฏิบัติของเราในการสร้างเอกสารผลิตภัณฑ์ผ่าน Apidog ก่อนหน้านั้น หากคุณต้องการดูผลลัพธ์ที่เฉพาะเจาะจงของเอกสารผลิตภัณฑ์ของ Apidog อย่างใกล้ชิด คุณสามารถตรวจสอบเอกสารช่วยเหลือของ Apidog ได้เลย – ยินดีรับฟังข้อเสนอแนะ

พื้นหลัง

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

กระบวนการข้างต้นไม่จำเป็นต้องมีบุคลากรด้านเทคนิคเข้ามาเกี่ยวข้อง – การดำเนินงานทั้งหมดที่เกี่ยวข้องกับเอกสารผลิตภัณฑ์จะดำเนินการโดยเพื่อนร่วมงานจากสองแผนกนี้ ถัดไป ฉันจะอธิบายวิธีการดำเนินงานสร้างเอกสารผลิตภัณฑ์ผ่าน Apidog ให้เสร็จสิ้นตามกระบวนการนี้

กระบวนการหลัก

1. สร้าง Sprint Branch สำหรับการจัดการเนื้อหาและการทำงานร่วมกัน

หลังจากที่การพัฒนาเวอร์ชันใหม่เริ่มต้นขึ้น เพื่อนร่วมงานฝ่ายปฏิบัติการจะสร้าง iteration branch ใน Apidog เพื่อวางเอกสารทั้งหมดที่เกี่ยวข้องกับการเปลี่ยนแปลงในเวอร์ชันปัจจุบันไว้ใน branch นี้สำหรับการทำงานร่วมกัน เพื่อหลีกเลี่ยงผลกระทบโดยตรงต่อ main branch

หลังจากสร้างแล้ว ผู้จัดการผลิตภัณฑ์จะนำเข้าเอกสารที่มีอยู่ซึ่งต้องแก้ไขมายัง iteration branch นี้ โดยอิงตามคุณสมบัติที่อัปเดตจริงในเวอร์ชันนั้นๆ และสร้างเอกสารใหม่สำหรับคุณสมบัติใหม่โดยตรงใน iteration branch การดำเนินการที่นี่สอดคล้องกับการใช้งาน iteration branch สำหรับเอกสาร API อย่างสมบูรณ์

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

2. ใช้ Markdown Editor ที่สวยงามเพื่อเขียนเอกสารแต่ละฉบับ

ผู้จัดการผลิตภัณฑ์จะใช้ Markdown เพื่อเขียนเอกสารที่ต้องอัปเดตในเวอร์ชันปัจจุบันภายใน iteration branch ฟังก์ชัน Markdown ของ Apidog ทรงพลังมาก ด้วยส่วนประกอบภาพต่างๆ ที่สามารถคลิกเพื่อแทรกสไตล์ที่ซับซ้อนได้มากมายโดยมีอุปสรรคในการเริ่มต้นต่ำ ทำให้คุณสามารถเขียนบทความที่สวยงามได้อย่างง่ายดายโดยไม่ต้องใช้ความพยายามเพิ่มเติม

นอกจากการแทรกภาพสไตล์ MD ทั่วไปแล้ว Apidog ยังได้เพิ่มคุณสมบัติพิเศษดังต่อไปนี้:

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

• **มีฟังก์ชันการแทรกทรัพยากรที่หลากหลาย เช่น ไอคอน, บล็อกไฮไลต์, ตาราง, ขั้นตอน, Mermaid, วิดีโอ เป็นต้น** เพื่อให้คุณไม่ต้องเสียเวลาค้นหาทรัพยากรด้วยตัวเองหรือเรียนรู้ไวยากรณ์สไตล์ MD เพื่อทำให้เอกสารดูดีขึ้น

3. เพื่อนร่วมงานฝ่ายผลิตภัณฑ์/ปฏิบัติการทำงานร่วมกันเพื่อขัดเกลาเอกสาร

หลังจากที่ผู้จัดการผลิตภัณฑ์เขียนเอกสารเวอร์ชันเริ่มต้นใน iteration branch เพื่อปรับปรุงคุณภาพเอกสาร ความชัดเจน และประโยชน์ต่อผู้ใช้ พวกเขาจะส่งมอบเอกสารให้เพื่อนร่วมงานฝ่ายปฏิบัติการอ่านจากมุมมองของผู้ใช้และให้ข้อเสนอแนะในการแก้ไขเพื่อขัดเกลา

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

ตอนนี้ เมื่อใช้ Apidog ทั้งสองฝ่ายสามารถแก้ไขเอกสารได้โดยตรง โดยมีการแจ้งเตือนข้อความแบบเรียลไทม์ส่งไปยัง IM เมื่อมีการเปลี่ยนแปลง ทำให้ผู้อื่นสามารถเข้าสู่เอกสารได้ทันทีและเห็นการเปลี่ยนแปลงที่เฉพาะเจาะจงได้อย่างง่ายดาย ซึ่งช่วยปรับปรุงประสิทธิภาพการทำงานร่วมกันได้อย่างมาก นี่คือขั้นตอนเฉพาะ:

• ผู้จัดการผลิตภัณฑ์สร้างเอกสารเวอร์ชันเริ่มต้น หลังจากเจ้าหน้าที่ฝ่ายปฏิบัติการเห็นการแจ้งเตือน พวกเขาจะอ่านเอกสารและ**ทำการแก้ไขเนื้อหาที่ต้องการเปลี่ยนแปลงภายในเอกสารนี้โดยตรง**
• การแก้ไขจะแจ้งเตือนโดยอัตโนมัติเมื่อบันทึก โดยส่งการ์ดข้อความการเปลี่ยนแปลงไปยังกลุ่ม IM ที่กำหนดค่าไว้ล่วงหน้า หลังจากสมาชิกกลุ่มเห็นการ์ดข้อความสรุปการเปลี่ยนแปลง พวกเขาสามารถคลิกที่ลิงก์การแจ้งเตือนเพื่อเข้าสู่เอกสารที่เกี่ยวข้องได้ด้วยคลิกเดียว
• **ผ่านประวัติการแก้ไข** เปรียบเทียบความแตกต่างโดยเลือกเวอร์ชันปัจจุบันและเวอร์ชันต้นฉบับ เพื่อดูการแก้ไขของอีกฝ่ายได้อย่างง่ายดาย และตัดสินใจว่าจะปรับเอกสารอย่างไร คุณสามารถเลือกที่จะไม่ยอมรับข้อเสนอแนะและกู้คืนเป็นเวอร์ชันต้นฉบับ หรือยอมรับการแก้ไขและเก็บเวอร์ชันล่าสุด

ทีมผลิตภัณฑ์และปฏิบัติการทำซ้ำขั้นตอนข้างต้นจนกว่าเนื้อหาเอกสารจะได้รับการขัดเกลาและกำหนดเวอร์ชันที่ทุกคนอนุมัติ

4. การเตรียมการและตรวจสอบก่อนการเผยแพร่เอกสารอย่างเป็นทางการ

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

ฝ่ายปฏิบัติการยืนยันเอกสารเนื้อหาที่เสร็จสมบูรณ์จากเวอร์ชันนี้ เลือกเอกสารเหล่านั้น และส่งคำขอ MR เพื่อรวมเข้ากับ main branch

ผู้จัดการฝ่ายปฏิบัติการหรือผู้ดูแลโปรเจกต์คนอื่นๆ จะตรวจสอบเนื้อหาเอกสารที่จะเผยแพร่ ยืนยันว่าถูกต้อง จากนั้นจึงเลือกที่จะรวมเข้ากับ main branch

หลังจากรวมเสร็จสมบูรณ์ เมื่อผู้ใช้เข้าถึงเอกสารที่เผยแพร่ พวกเขาก็จะเห็นเนื้อหาล่าสุดที่รวมเข้ากับ main branch

ข้อดีอื่นๆ

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

1. ตั้งค่าสไตล์เว็บไซต์เอกสารโดยรวมให้เข้ากับสไตล์ผลิตภัณฑ์/บริษัท

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

เอกสารช่วยเหลือของ Apidog ได้ตั้งค่าโลโก้ของตัวเองและลิงก์ทรัพยากรที่เกี่ยวข้องกับ Apidog บางส่วน ด้านซ้ายบนมีโลโก้บริษัท ด้านขวาบนมีลิงก์ทรัพยากรต่างๆ ที่เกี่ยวข้องกับบริษัท และเอกสาร API แบบเปิดที่นักพัฒนาให้ความสำคัญมากกว่าก็ถูกตั้งค่าไว้ในเอกสารผลิตภัณฑ์ด้วย:

2. ประสบการณ์การเผยแพร่ที่ไม่ต้องบำรุงรักษา

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

แน่นอนว่า หากคุณต้องการให้เอกสารดูเหมือนเว็บไซต์บริษัทของคุณมากขึ้น เราก็มีฟังก์ชันโดเมนที่กำหนดเองให้ใช้งาน ซึ่งช่วยให้คุณสามารถใช้โดเมนของบริษัทคุณเองเพื่อเข้าถึงเอกสารได้

คุณยังสามารถตั้งค่าการค้นหาทั่วไป, การค้นหาข้อความเต็ม Algolia, การรวม GA, การตั้งค่าการเปลี่ยนเส้นทาง (redirects) และความสามารถขั้นสูงอื่นๆ ในเว็บไซต์เอกสารผลิตภัณฑ์ที่เผยแพร่ได้อย่างง่ายดายด้วยการดำเนินการง่ายๆ การตั้งค่าเหล่านี้ไม่ต้องการให้ผู้ปฏิบัติงานมีความสามารถทางวิศวกรรมเพียงพอ – สามารถตั้งค่าได้อย่างง่ายดายโดยทำตามคำแนะนำอินเทอร์เฟซและเอกสารช่วยเหลือ

3. การตั้งค่าที่เป็นมิตรต่อ SEO หลายประการ

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

แน่นอนว่า หากคุณมีความต้องการ SEO ที่ซับซ้อนมากขึ้น ก็ยังรองรับการกำหนด Slug, Meta Data และการตั้งค่าเนื้อหาอื่นๆ ที่หลากหลายสำหรับเอกสารแต่ละฉบับ

สรุป

ข้างต้นคือแนวปฏิบัติเฉพาะของการใช้ Apidog สำหรับการบำรุงรักษาเอกสารผลิตภัณฑ์

นอกเหนือจากเนื้อหาที่กล่าวมาข้างต้น เรายังสามารถบำรุงรักษาเอกสารช่วยเหลือผลิตภัณฑ์ เอกสารสำหรับนักพัฒนา และเอกสาร API ในรูปแบบเดียวกัน และเชื่อมโยงทั้งหมดเข้าด้วยกัน ซึ่งจะมอบประสบการณ์ผู้ใช้ที่ดียิ่งขึ้น หากสถานการณ์จริงของคุณเหมาะสม ยินดีให้ลองใช้แนวปฏิบัตินี้และแนะนำให้เพื่อนร่วมงานคนอื่นๆ เราหวังว่าสิ่งนี้จะนำมาซึ่งการปรับปรุงประสิทธิภาพและคุณภาพบางส่วนให้กับงานสร้างเอกสารผลิตภัณฑ์ของคุณ