โปรเจ็กต์ Rocket.Chat

หน้านี้มีรายละเอียดของโปรเจ็กต์การเขียนเชิงเทคนิคที่ได้รับการยอมรับสำหรับ Google Season of Docs

สรุปโปรเจ็กต์

องค์กรโอเพนซอร์ส

Rocket.Chat

นักเขียนเชิงเทคนิค

มิสเตอร์โกลด์

ชื่อโปรเจ็กต์:

เอกสารของบ็อต

ระยะเวลาของโปรเจ็กต์

ระยะเวลามาตรฐาน (3 เดือน)

คำอธิบายโปรเจ็กต์

สรุปโปรเจ็กต์

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

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

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

ปัญหาเกี่ยวกับโปรเจ็กต์

ต่อไปนี้เป็นรายการปัญหาที่สําคัญที่สุดซึ่งเกี่ยวข้องกับเอกสารประกอบของบ็อต

1. ข้อมูลทั่วไปเกี่ยวกับบ็อตที่ใช้งานยากและไม่เข้าใจง่าย
2. ส่วนที่เกี่ยวข้องกับสถาปัตยกรรมบ็อตกระจายอยู่และซ้ำซ้อน
3. วิธีการ "เริ่มต้นใช้งาน" ที่ไม่สอดคล้องกันซึ่งไม่มีแหล่งข้อมูลที่ถูกต้องเพียงแหล่งเดียว
4. ไม่มีวิธีการหรือรายละเอียดวิธีการมากเกินไป
5. เอกสารประกอบของ Bot SDK ที่ไม่ชัดเจนและคลุมเครือ

โปรเจ็กต์ข้อเสนอ

รายการการเพิ่มประสิทธิภาพที่เสนอตามเป้าหมายของโปรเจ็กต์และปัญหาที่ระบุไว้ข้างต้นมีดังนี้

1. อัปเดตเอกสารของบ็อต คุณควรอัปเดตเอกสารต่อไปนี้โดยค่อยๆ เปลี่ยนจากเนื้อหาที่เข้าใจง่ายไปเป็นเนื้อหาที่ซับซ้อนมากขึ้น เพื่อให้การเปิดตัวครั้งแรกราบรื่นและสอดคล้องกัน

   • ภาพรวมของบ็อต: https://rocket.chat/docs/bots/
   • สถาปัตยกรรมของบ็อต: https://rocket.chat/docs/bots/bots-architecture/
   • การกำหนดค่าสภาพแวดล้อมบ็อต: https://rocket.chat/docs/bots/configure-bot-environment/
   • หน้าแรกของบ็อต: https://github.com/RocketChat/rocketchat.github.io/pull/

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

3. แก้ไขงานนำเสนอเกี่ยวกับเอกสาร Rocket.Chat JS SDK เอกสารประกอบ SDK ควรสร้างขึ้นแบบเป็นโปรแกรมจากซอร์สโค้ดโดยใช้เครื่องมือเฉพาะ การปรับปรุงนี้จะช่วยให้อ่านได้ง่ายและไม่ต้องอัปเดตเอกสารใน Github ด้วยตนเองทุกครั้งที่มีการเปลี่ยนแปลงเมธอด (หรือสิ่งที่อยู่ภายใน)

ไทม์ไลน์

ระยะเวลาตรวจสอบใบสมัคร: ทำความคุ้นเคยกับชุมชนและคนที่จะร่วมงานด้วย ดูคู่มือและแนวทางปฏิบัติแนะนำเกี่ยวกับการมีส่วนร่วมของชุมชน มีส่วนร่วมครั้งแรก

การสร้างความสัมพันธ์ในชุมชน: สำรวจชุมชน ตรวจสอบสถานะปัจจุบันของเอกสารประกอบของบ็อต ระบุจุดอ่อน

สัปดาห์ที่ 1: ที่สอดคล้องกับที่ปรึกษาเกี่ยวกับวิสัยทัศน์ใหม่ของบ็อต สร้างเนื้อหาที่อัปเดตสำหรับหน้าแรกของบ็อตใหม่ตามวิสัยทัศน์นั้น

สัปดาห์ที่ 2: แก้ไขภาพรวม สถาปัตยกรรม การกำหนดค่าของหน้าสภาพแวดล้อมของบอท

สัปดาห์ที่ 3 - กําหนดรายการโปรเจ็กต์ย่อย (ที่เก็บ GitHub ของบ็อต) ที่ควรโอนไปยังเอกสารประกอบหลัก - กำหนดวิธีที่เว็บไซต์บ็อตควรทำงานหลังจากการโอน - กำหนดเทมเพลตที่จะใช้เพื่อจัดระเบียบข้อมูลภายในที่เก็บเหล่านี้ - เตรียมเอกสารหลักสำหรับการโอน

สัปดาห์ที่ 4: โอนที่เก็บ bBot จัดระเบียบข้อมูลตามเทมเพลตที่กําหนด

สัปดาห์ที่ 5: โอนที่เก็บ Hubot จัดระเบียบข้อมูลตามเทมเพลตที่กำหนด

สัปดาห์ที่ 6: โอนรีโป Botkit จัดระเบียบข้อมูลตามเทมเพลตที่กําหนด

สัปดาห์ที่ 7: โอนที่เก็บของ Rasa จัดระเบียบข้อมูลตามเทมเพลตที่กำหนด

สัปดาห์ที่ 8: โอนที่เก็บของ BotPress จัดระเบียบข้อมูลตามเทมเพลตที่กําหนด

สัปดาห์ที่ 9: สรุปโครงสร้างและหน้าเอกสารประกอบหลักหลังจากโอนโปรเจ็กต์ย่อยของบอททั้งหมดแล้ว

สัปดาห์ที่ 10: ตรวจสอบการกำหนดค่า JSDoc กำหนดตำแหน่งที่จะจัดเก็บอาร์ติแฟกต์ JSDoc เริ่มบันทึกวิธีการของไดรเวอร์

สัปดาห์ที่ 11: เขียนวิธีการของไดรเวอร์ให้เสร็จ

สัปดาห์ที่ 12: ประเมินผลลัพธ์

รายละเอียดของเหตุการณ์สำคัญ

ระยะเวลาตรวจสอบใบสมัคร

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

ส่วนที่สองของระยะเวลานี้จะเน้นไปที่การตรวจสอบวัฒนธรรมการมีส่วนร่วมโดยทั่วไป การตรวจสอบคู่มือการมีส่วนร่วมและแนวทางปฏิบัติแนะนำ นี่จะเป็นเวลาที่การมีส่วนร่วมเป็นครั้งแรกเพื่อดูว่าขั้นตอนนี้ทำงานอย่างไร

การสานสัมพันธ์ในชุมชน

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

สัปดาห์ที่ 1 - สัปดาห์ที่ 2

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

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

เอกสารฉบับแก้ไขจะเน้นหัวข้อต่อไปนี้อย่างชัดเจน - นักพัฒนาซอฟต์แวร์รายใหม่ที่ต้องการสร้างบ็อตของตัวเอง - นักพัฒนาซอฟต์แวร์ [บ็อต] มืออาชีพที่ต้องการออกแบบ/เขียนโค้ด/ทดสอบบ็อตโดยใช้แพลตฟอร์มฟรีและใช้งานง่าย หรือปรับให้เข้ากับบ็อตที่มีอยู่ในแพลตฟอร์มดังกล่าว - นักพัฒนาบ็อตมืออาชีพที่มีกรอบการทำงานที่ต้องการสร้างบ็อตสำหรับ Rocket.Chat

ขอบเขตการทำงานมีดังนี้

1. นำส่วนที่ซ้ำซ้อนออก ตัวอย่างเช่น ส่วนต่อไปนี้มีข้อมูลที่ทับซ้อนกัน
   • บ็อตส่งและรับข้อความได้อย่างไร ในภาพรวมของบ็อต (https://rocket.chat/docs/bots/#how-do-bots-send-and-receive-messages)
   • สตรีมข้อความในสถาปัตยกรรมบ็อต (https://rocket.chat/docs/bots/bots-architecture/#message-streams)
   • พูดคุยกับบ็อตในการสร้างผู้ใช้บ็อต (https://rocket.chat/docs/bots/creating-bot-users/#Talk-to-your-bot)

2. แก้ไขส่วนต่างๆ และวลีของหน้าภาพรวมของบ็อตเพื่อให้อธิบายระบบนิเวศและฟังก์ชันการทำงานของบ็อตอย่างชัดเจนตามหลักการ DRY

   แก้ไขส่วนและวลีเกี่ยวกับข้อมูล ""เบื้องหลัง""

   • ความหมายของบ็อตจากมุมมองทางเทคนิค
   • องค์ประกอบของเนื้อหา
   • วิธีที่องค์ประกอบเหล่านี้ทำงานร่วมกัน

3. เขียนคู่มือเริ่มใช้งานฉบับย่อซึ่งอธิบายขั้นตอนที่จำเป็นในการสร้างบ็อต (พร้อมลิงก์ไปยัง ""การกำหนดค่าสภาพแวดล้อมบ็อต"" เพื่ออ่านเพิ่มเติม) คำแนะนำนี้อยู่ในหน้า "การกำหนดค่าสภาพแวดล้อม"

ทำให้นักพัฒนาซอฟต์แวร์มองเห็นลักษณะของบ็อตได้ชัดเจนและบ็อตสามารถทำอะไรได้บ้าง จากนั้นนักพัฒนาซอฟต์แวร์จะสามารถสร้างบ็อตแรกได้

สิ่งที่ส่งมอบ: คำแนะนำเบื้องต้นที่แก้ไขและทำตามได้ง่าย มีข้อมูลเกี่ยวกับระบบนิเวศและสถาปัตยกรรมของบ็อต

สัปดาห์ที่ 3 - 9

สัปดาห์ที่ 3-9 จะเน้นที่การรวมเอกสารของบอททั้งหมดในที่เก็บข้อมูล GitHub และโอนเอกสารเหล่านี้ไปยังเอกสารประกอบหลัก (https://rocket.chat/docs/bots/) กิจกรรมเหล่านี้แบ่งออกเป็นหลายรอบได้ดังนี้

1. คำจำกัดความ

   กำหนดรายการโปรเจ็กต์ย่อยของบอทที่ควรย้ายข้อมูลไปยังเอกสารประกอบหลัก กำหนดวิธีที่เว็บไซต์บ็อตจะทำงานหลังจากการโอน (บ็อตบางตัว, Bbot เช่น (http://bbot.chat)) มีเว็บไซต์แยกต่างหากพร้อมเอกสารประกอบนอกเหนือจาก GitHub)

2. เทมเพลต

   กําหนดค่าและสร้างเทมเพลต (วิธี) ในการจัดระเบียบข้อมูลภายในโปรเจ็กต์ย่อยของบ็อตที่กําหนดไว้ในขั้นตอนที่ 1 เทมเพลตนี้อาจมีลักษณะดังนี้

   ก. โคลนที่เก็บ

   ข. ติดตั้งการอ้างอิง

   ค. กำหนดค่าบ็อต

   ง. เรียกใช้บ็อต

   จ. การกำหนดค่าขั้นสูง

   ฉ. ขั้นตอนถัดไป

   คำสั่งที่มีเอาต์พุตที่ไม่ได้สำคัญบางอย่าง (เช่น "เรียกใช้บ็อต") ควรมาพร้อมกับการนำเสนอเอาต์พุตนั้นโดยใช้เครื่องมือชีตข้อกำหนด (https://neatsoftware.github.io/term-sheets/)

   นอกจากนี้ เราจะรวมขั้นตอนทั้งหมดไว้ในงานนำเสนอแบบสดงานเดียวเพื่อให้ระยะเริ่มต้น "เริ่มใช้งานฉบับย่อ" (ขั้นตอน ก - ง) ชัดเจนยิ่งขึ้น

   คุณควรแสดงตัวอย่างโค้ดพร้อมกับสภาพแวดล้อมพื้นที่ทดสอบ (โดยใช้ Glitch ซึ่งเป็นส่วนหนึ่งของระบบนิเวศ Rocket Chat) เพื่อให้ผู้มาใหม่รู้สึกปลอดภัยจากข้อผิดพลาดที่อาจเกิดขึ้น ซึ่งผู้มาใหม่สามารถแชทกับบ็อตที่มี "ตัวอย่างโค้ด" อยู่เบื้องหลัง

3. การเตรียมพร้อม

   เตรียมเอกสารหลักสำหรับการโอน ซึ่งรวมถึงการสร้างโฟลเดอร์และโครงสร้างหน้าเว็บที่เหมาะสม ตลอดจนการปรับสารบัญตามโครงสร้างดังกล่าว

   โครงสร้างสุดท้ายอาจมีลักษณะดังนี้

   • บ็อต
     • สถาปัตยกรรมของบ็อต
     • สร้างผู้ใช้บ็อต
     • กำหนดค่าสภาพแวดล้อมของบ็อต
     • เรียกใช้บ็อต
       • บ็อต bBot
       • บ็อต Hubot
       • บ็อต Botkit
       • บ็อต Rasa
       • บ็อต Botpress

4. การย้ายข้อมูล

   ย้ายข้อมูลโปรเจ็กต์ย่อยของบอทที่กําหนดไปยังเอกสารประกอบหลักทีละโปรเจ็กต์ เอกสารประกอบของบอทแต่ละรายการจะมีหน้าแยกต่างหากพร้อมส่วนย่อยต่างๆ เช่น เวอร์ชันปัจจุบัน (เช่น เรียกใช้ bBot)

   • เรียกใช้บ็อต
     • บ็อต bBot
     • บ็อต Hubot
     • บ็อต Botkit
     • บ็อต Rasa
     • บ็อต Botpress

5. องค์กร

   โดยจะมีกิจกรรมหลายอย่างดังนี้

   1. จัดระเบียบข้อมูลจากรีโป GitHub ของบ็อตแต่ละรายการตามเทมเพลตที่กําหนดไว้ในขั้นตอนที่ 2
   2. ย้ายคอมโพเนนต์ทั่วไป (เช่น ตัวแปรสภาพแวดล้อม) ที่เกี่ยวข้องกับโปรเจ็กต์ย่อยของบอททั้งหมดขึ้น 1 ระดับในลําดับชั้นของเอกสารประกอบหลัก และลิงก์โปรเจ็กต์ย่อยของบอทกับคอมโพเนนต์เหล่านี้
   3. การสร้างตัวอย่างบอท "Hello World" สําหรับเฟรมเวิร์กแต่ละรายการที่รองรับ ตัวอย่างนี้จะใช้เป็นบอท "เริ่มต้นใช้งาน" สําหรับ Rocket.Chat

ทำไมประเด็นนี้จึงสำคัญ โปรเจ็กต์ย่อยทั้ง 8 โปรเจ็กต์ที่ Rocket.Chat สนับสนุน ได้แก่ alexa, Hubot, chatops-gitsy, botpress, rasa, bbot, botkit, BOTswana, Hubot-gitsy มีเอกสารที่กระจัดกระจายในรูปแบบของนักพัฒนาซอฟต์แวร์ README ไฟล์ README เหล่านี้ไม่มีโครงสร้างใดๆ เลย มีข้อมูลล้าสมัยเกี่ยวกับวิธีเริ่มต้นใช้งาน หรือมีข้อมูลมากเกินไป (บางครั้งมีข้อมูลซ้ำกัน 3 ครั้ง เช่น hubot (https://github.com/RocketChat/hubot-rocketchat) เกี่ยวกับวิธีเรียกใช้บ็อตโดยใช้ Docker) รวมถึงตารางที่มีตัวแปรของสภาพแวดล้อม

แง่มุมเหล่านี้ทำให้นักพัฒนาซอฟต์แวร์ (ในฐานะมือใหม่) สับสนกับรายละเอียดมากมายมหาศาล ด้วยเหตุนี้ นักพัฒนาซอฟต์แวร์จึงไม่สามารถทำให้บ็อตทำงานได้โดยใช้คำสั่งเทอร์มินัลเพียงไม่กี่คำสั่ง

หลังจากการโอนและการเพิ่มประสิทธิภาพเสร็จสมบูรณ์แล้ว ที่เก็บข้อมูลบอทที่มีอยู่เดิมใน github จะมีไฟล์ README ที่อ้างอิงถึงเอกสารประกอบหลัก

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

ผลงาน: จัดระเบียบไว้ในที่เดียว (เอกสารหลัก) วิธีการที่เข้าใจง่ายเกี่ยวกับวิธีสร้าง กำหนดค่า และเรียกใช้บ็อตที่ Rocket.Chat รองรับ

สัปดาห์ที่ 10

สัปดาห์นี้จะเน้นไปที่การกำหนดค่า JSDoc (https://devdocs.io/jsdoc/) เพื่อเพิ่มมูลค่าของความคิดเห็นในบรรทัดให้ได้สูงสุด ซึ่งรวมถึงเนื้อหาต่อไปนี้

1. ตรวจสอบว่า JSDoc ได้รับการกําหนดค่าอย่างถูกต้องเพื่อแยกวิเคราะห์ความคิดเห็นสําหรับเมธอดไดรเวอร์ (https://github.com/RocketChat/Rocket.Chat.js.SDK#driver-methods)
2. ติดตั้ง postman-jsdoc-theme (https://github.com/postmanlabs/postman-jsdoc-theme) เพื่อให้เอาต์พุต HTML ที่ออกมาชัดเจนและเหมาะสำหรับนักพัฒนาซอฟต์แวร์มากขึ้น
3. กำหนดตำแหน่งที่จะเผยแพร่อาร์ติแฟกต์เอกสารประกอบ JSDoc
4. อธิบายฟังก์ชันทั้งหมด (ในไฟล์ dist/lib/driver.js) ที่เกี่ยวข้องกับเมธอดของไดรเวอร์ ซึ่งรวมถึง
   • การเพิ่ม/แก้ไขคำอธิบายของวิธีการ
   • การเพิ่ม/แก้ไขคําอธิบายพารามิเตอร์ของเมธอด
   • การเพิ่ม/การแก้ไขตัวอย่างคำขอเมธอด (หากมี)
   • การเพิ่ม/แก้ไขตัวอย่างการตอบกลับของเมธอด (หากมี)

เอกสารประกอบในบรรทัดเขียนและดูแลรักษาได้ง่ายกว่าจากมุมมองของนักพัฒนาซอฟต์แวร์ และกลไกการสร้างอัตโนมัติช่วยให้คุณกำจัดเอกสารประกอบแบบคงที่ที่โฮสต์ใน GitHub (https://github.com/RocketChat/Rocket.Chat.js.SDK#driver-methods) ซึ่งต้องอัปเดตแยกต่างหากเมื่อมีการเปลี่ยนแปลงวิธีการของ SDK แต่ละรายการ

สัปดาห์ที่ 11

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

สัปดาห์ที่ 12

การสรุปงานที่ทำเสร็จแล้ว การตรวจสอบการยอมรับ