پروژه Rocket.Chat

این صفحه حاوی جزئیات یک پروژه نگارش فنی است که برای فصل اسناد Google پذیرفته شده است.

خلاصه پروژه

سازمان منبع باز:

موشک.چت

نویسنده فنی:

آقای گلد

نام پروژه:

Bot Docs

طول پروژه:

طول استاندارد (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 - لیستی از پروژه های فرعی (bot github repo) که باید به مستندات اصلی منتقل شوند را تعریف کنید. - نحوه عملکرد وب سایت های ربات پس از انتقال را مشخص کنید. - الگویی را تعریف کنید که برای سازماندهی اطلاعات در این مخازن استفاده می شود. - اسناد اصلی را برای انتقال آماده کنید

هفته 4: انتقال مخزن bBot. سازماندهی اطلاعات بر اساس الگوی تعریف شده

هفته 5: انتقال مخزن Hubot. سازماندهی اطلاعات بر اساس الگوی تعریف شده

هفته 6: انتقال مخزن Botkit. سازماندهی اطلاعات بر اساس الگوی تعریف شده

هفته هفتم: انتقال مخزن رسا. سازماندهی اطلاعات بر اساس الگوی تعریف شده

هفته 8: انتقال مخزن BotPress. سازماندهی اطلاعات بر اساس الگوی تعریف شده

هفته نهم: نهایی شدن ساختار اسناد اصلی و صفحات پس از انتقال تمام پروژه های فرعی ربات

هفته 10: پیکربندی JSDoc را بررسی کنید. مکانی را برای ذخیره مصنوعات JSDoc تعریف کنید. مستندسازی روش های درایور را شروع کنید

هفته یازدهم: مستندسازی روش های درایور را به پایان برسانید

هفته دوازدهم: نتایج را ارزیابی کنید

تفصیل نقاط عطف

دوره بررسی برنامه

بخش اول دوره به بررسی کانال‌های انجمن و کد منبع و تماس با افرادی که به پروژه اختصاص داده شده‌اند اختصاص خواهد داشت.

بخش دوم این دوره به بررسی فرهنگ مشارکت به طور کلی، بررسی راهنماهای مشارکت و بهترین شیوه ها اختصاص خواهد یافت. این زمان برای اولین مشارکت ها خواهد بود تا نحوه عملکرد جریان را ببینیم.

پیوند جامعه

این زمان به بررسی عمیق تر مخزن اسناد و نقشه راه آن اختصاص خواهد یافت. بر اساس آن اطلاعات، شناسایی نقاط ضعف (مثلاً قسمت‌های ناقص یا گمشده) که قابل بهبود هستند، امکان‌پذیر خواهد بود. برای پر کردن شکاف‌ها، درخواست‌های کشش (در صورت امکان) ایجاد کنید.

هفته 1 - هفته 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)
   • در Creating Bot Users با ربات خود صحبت کنید (https://rocket.chat/docs/bots/creating-bot-users/#talk-to-your-bot)

2. بخش‌ها و عبارات صفحه نمای کلی ربات‌ها را اصلاح کنید تا به وضوح اکوسیستم و عملکرد ربات‌ها را طبق اصل DRY توصیف کنید.

   بخش‌ها و عبارات مربوط به اطلاعات ""زیر سرپوش"" را اصلاح کنید:

   • از منظر فنی چه رباتی است
   • از چه اجزایی تشکیل شده است
   • نحوه کار این اجزا با هم

3. یک راهنمای شروع سریع بنویسید که مراحل مورد نیاز برای ایجاد یک ربات را توضیح دهد (با پیوندی به ""پیکربندی محیط های ربات"" در ادامه مطلب). این راهنما در صفحه Configuration of Environment قرار خواهد گرفت.

به این ترتیب، یک توسعه‌دهنده دید واضحی از ماهیت ربات‌ها و آنچه که ربات‌ها قادر به انجام آن هستند، خواهد داشت. از آن نقطه، یک توسعه دهنده می تواند اولین ربات خود را ایجاد کند.

موارد تحویلی: دستورالعمل‌های معرفی اصلاح‌شده و آسان با اطلاعاتی در مورد اکوسیستم و معماری ربات‌ها.

هفته 3 تا 9

هفته های 3 تا 9 به یکپارچه سازی تمام اسناد ربات در مخازن github و انتقال این اسناد به اسناد اصلی (https://rocket.chat/docs/bots/) اختصاص خواهد یافت. این فعالیت ها را می توان به چندین تکرار تقسیم کرد:

1. تعریف

   تعریف لیستی از پروژه های فرعی ربات که باید به مستندات اصلی منتقل شوند. تعریف کنید که وب سایت های ربات چگونه باید پس از انتقال کار کنند (بعضی از ربات ها، bbot، به عنوان مثال (http://bbot.chat)) علاوه بر github دارای سایت های جداگانه با مستندات هستند).

2. الگو

   تعریف و ایجاد یک الگو (روشی) برای سازماندهی اطلاعات در زیر پروژه های ربات تعریف شده در مرحله اول. این قالب ممکن است به شکل زیر باشد:

   الف یک مخزن را شبیه سازی کنید

   ب وابستگی ها را نصب کنید

   ج یک ربات را پیکربندی کنید

   د یک ربات را اجرا کنید

   ه. پیکربندی پیشرفته

   f. مراحل بعدی

   دستوراتی که شامل برخی خروجی‌های غیر ضروری هستند (مانند «روبات را اجرا کنید») باید با ارائه‌های زنده آن خروجی با استفاده از ابزار Term Sheets (https://neatsoftware.github.io/term-sheets/) همراه شوند.

   علاوه بر این، برای واضح‌تر کردن مرحله اولیه «شروع سریع» (مراحل الف - د)، تمام مراحل نیز در یک ارائه زنده ترکیب می‌شوند.

   برای اینکه تازه واردان از شکست‌های احتمالی در امان باشند، نمونه‌هایی از کد باید با محیط زمین بازی (با استفاده از Glitch، به عنوان بخشی از اکوسیستم Rocket Chat) ارائه شود، جایی که تازه‌واردها می‌توانند با ربات‌هایی که «کد مثال» را در زیر دارند چت کنند. کاپوت

3. آماده سازی

   تهیه اسناد اصلی برای انتقال. این شامل ایجاد پوشه و ساختار صفحه مناسب و همچنین تنظیم فهرست مطالب بر اساس آن ساختار است.

   ساختار نهایی ممکن است به صورت زیر باشد:

   • ربات ها
     • معماری ربات ها
     • ایجاد کاربران ربات
     • پیکربندی محیط ربات
     • ربات ها را اجرا کنید
       • bBot ربات
       • ربات Hubot
       • Botkit Bot
       • رسا بات
       • Botpress Bot

4. مهاجرت

   انتقال پروژه های فرعی ربات تعریف شده به مستندات اصلی یک به یک. هر بخش از مستندات ربات دارای یک صفحه جداگانه با بخش های فرعی مانند نسخه فعلی خواهد بود (به عنوان مثال اجرای bBot).

   • ربات ها را اجرا کنید
     • bBot ربات
     • ربات Hubot
     • Botkit Bot
     • رسا بات
     • Botpress Bot

5. سازمان

   چندین فعالیت وجود خواهد داشت:

   1. سازماندهی اطلاعات هر ربات github repo طبق الگوی تعریف شده در مرحله دوم.
   2. جابجایی اجزای مشترک (مثلاً متغیرهای محیطی) که به تمام پروژه‌های فرعی ربات مربوط می‌شوند، در سلسله مراتب مستندات اصلی یک سطح به بالا و پیوند پروژه‌های فرعی ربات به این مؤلفه‌ها.
   3. ایجاد نمونه ای از ربات "Hello world" برای هر فریم ورک پشتیبانی شده. این مثال به عنوان یک ربات "شروع به کار" برای Rocket.Chat استفاده خواهد شد.

چرا این مهم است؟ همه 8 پروژه فرعی پشتیبانی شده توسط Rocket.Chat: alexa، hubot، chatops-gitsy، botpress، rasa، bbot، botkit، BOTswana، hubot-gitsy دارای اسناد پراکنده در قالب توسعه دهندگان READMEs هستند. این README ها اصلاً ساختاری ندارند، حاوی اطلاعات قدیمی در مورد نحوه شروع، یا حاوی اطلاعات بسیار زیادی هستند (گاهی اوقات با افزونگی سه گانه، مانند 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- متدها ) که باید در هر تغییر در متدهای SDK به طور جداگانه به روز شوند.

هفته 11

این هفته به طور کامل به نهایی شدن تشریح روش های درایور اختصاص خواهد داشت. پس از تکمیل، توضیحات از نظر دقت و سازگاری آزمایش می‌شوند و سپس مستندات جدید در جهان منتشر می‌شوند.

هفته 12

نهایی شدن کار انجام شده. چک های پذیرش