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

หน้านี้มีรายละเอียดของโครงการเขียนเชิงเทคนิคที่ยอมรับใน Google Season of Docs

ข้อมูลสรุปของโปรเจ็กต์

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

Rocket.Chat

ผู้เขียนด้านเทคนิค:

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

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

เอกสารบ็อต

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

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

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

สรุปโครงการ

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

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

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

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

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

1. ข้อมูลทั่วไปเกี่ยวกับบ็อตที่ไม่ใช้งานง่ายและไม่เป็นมิตร
2. ส่วนที่กระจัดกระจายและส่วนซ้ำซ้อนที่เกี่ยวข้องกับสถาปัตยกรรมบ็อต
3. คำแนะนำ "การเริ่มต้นใช้งาน" ที่ยุ่งเหยิงโดยไม่มีแหล่งข้อมูลเพียงแหล่งเดียว
4. ไม่มีวิธีการหรือรายละเอียดการสอนมากเกินควร
5. เอกสารประกอบ 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. จัดระเบียบและรวมเอกสารประกอบการติดตั้งบ็อตเข้าไว้ด้วยกัน โปรเจ็กต์ย่อยทั้งหมดควรมีวิธีการแบบรวมสำหรับวิธีการโคลนที่เก็บบ็อตและติดตั้งทรัพยากร Dependency ที่จำเป็น วิธีเริ่มต้นใช้งานอย่างรวดเร็ว วิธีทำงานกับบ็อตหลังจากการเปิดตัวครั้งแรก และวิธีติดตั้งใช้งานบ็อต

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

ไทม์ไลน์

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

การเชื่อมโยงชุมชน: สำรวจชุมชน ตรวจสอบสถานะปัจจุบันของเอกสารบ็อต ระบุจุดอ่อน

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

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

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

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

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

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

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

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

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

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

สัปดาห์ที่ 11: เสร็จสิ้นการบันทึกวิธีของผู้ขับ

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

รายละเอียดเป้าหมายโดยละเอียด

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

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

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

การผูกพันชุมชน

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

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

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

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

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

ขอบเขตงานมีดังนี้

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/generate-bot-users/#talk-to-your-bot)

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

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

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

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

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

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

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

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

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

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

2. เทมเพลต

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

   • เรียกใช้บ็อต
     • บ็อต bBot
     • บ็อต Hubot
     • บ็อต Botkit
     • ราซา บ็อต
     • บ็อต 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

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