مشروع Rocket.Chat

تحتوي هذه الصفحة على تفاصيل مشروع كتابة فني مقبول في موسم Google من المستندات.

ملخص المشروع

مؤسسة مفتوحة المصدر:
Rocket.Chat
الكاتب التقني:
Mister Gold
اسم المشروع:
مستندات Bots
مدة المشروع:
مدة زمنية عادية (3 أشهر)

وصف المشروع

ملخّص المشروع

برامج التتبُّع في Chat هي أحدث ابتكارات التكنولوجيا في الوقت الحالي. إنّ زيادة معدلات النمو الإجمالية الضخمة في برامج الدردشة وبرامج التتبُّع، بالإضافة إلى ميزات التعرّف على الكلام والتشغيل الآلي المتزايدة، تفرض الحاجة إلى إنشاء مستندات لبرامج التتبُّع يسهل فهمها واستخدامها.

يصبح توفُّر مستندات شاملة وواضحة أكثر أهمية، لذا يجب تسهيل الوصول إلى مستندات الروبوتات الحالية والتنقّل فيها، ويجب أن تقدّم تعليمات مفصّلة موحّدة لكل إطار عمل متوافق، بالإضافة إلى أمثلة مفصّلة. يجب أيضًا ترتيبها للتخلص من المعلومات المتكررة والصعب فهمها.

ويهدف المشروع إلى سد الفجوة المعرفية وتشجيع المطوّرين الجُدد وذوي الخبرة الأقل على تقديم مزايا التكنولوجيا الحديثة لجمهور متحمّس. ويمكن تحقيق ذلك من خلال تزويد منشئي الروبوتات بتجربة سلسة لتطوير الروبوتات الخاصة بهم في Rocket.Chat. يهدف هذا الهدف إلى جعل Rocket.Chat المنصة المفضّلة المفتوحة المصدر لهؤلاء المطوّرين من أجل ابتكار أفكارهم حول محادثات الدردشة وإنشائها واختبارها، بغض النظر عن الهدف النهائي لنشر محادثات الدردشة.

مشاكل المشروع

في ما يلي قائمة بالمشاكل الأكثر أهمية في ما يتعلّق بمستندات برامج التتبّع:

  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. تنظيم وثائق تثبيت برامج التتبُّع وتوحيدها يجب أن تتضمّن جميع المشاريع الفرعية مجموعة موحّدة من التعليمات حول كيفية استنساخ مستودع برامج التتبّع وتثبيت التبعيات المطلوبة، وكيفية البدء بسرعة، وكيفية العمل مع برنامج التتبّع بعد الإطلاق الأول، وكيفية نشره.

  3. مراجعة العرض التقديمي لوثائق Rocket.Chat JS SDK يجب إنشاء مستندات حزمة تطوير البرامج (SDK) آليًا من رمز المصدر باستخدام أدوات مخصّصة. سيؤدي هذا التحسين إلى تحسين إمكانية القراءة وإزالة الحاجة إلى تعديل المستند على Github يدويًا في كل مرة تتغيّر فيها طريقة (أو أي شيء داخلها).

مجريات المباراة

فترة مراجعة الطلب: تعرّف على المنتدى والأشخاص الذين يمكنك التعامل معهم. اطّلِع على أدلة أفضل الممارسات المتعلقة بالمساهمة في المنتدى. تقديم المساهمات الأولى

التفاعل مع المنتدى: استكشاف المنتدى راجِع الحالة الحالية لوثائق الروبوت. تحديد نقاط الضعف

الأسبوع 1: التواصل مع المرشدين حول الرؤية الجديدة لبرامج التتبُّع. أنشئ محتوى معدّلاً للصفحة الرئيسية الجديدة لبرنامج "الروبوتات" وفقًا للرؤية.

الأسبوع 2: مراجعة "نظرة عامة على برامج التتبّع" و"البنية" و"إعداد صفحات البيئة"

الأسبوع 3 - تحديد قائمة بالمشاريع الفرعية (مستودعات GitHub للبوت) التي يجب نقلها إلى المستندات الرئيسية - تحديد كيفية عمل مواقع الروبوت بعد عملية النقل. - تحديد قالب سيتم استخدامه لتنظيم المعلومات داخل هذه المستودعات. - إعداد المستندات الرئيسية لعملية النقل

الأسبوع 4: نقل مستودع bBot تنظيم المعلومات وفقًا للنموذج المحدّد

الأسبوع 5: نقل مستودع Hubot تنظيم المعلومات وفقًا للنموذج المحدّد

الأسبوع 6: نقل مستودع Botkit تنظيم المعلومات وفقًا للنموذج المحدّد

الأسبوع 7: نقل مستودع Rasa تنظيم المعلومات وفقًا للنموذج المحدد

الأسبوع 8: نقل مستودع BotPress تنظيم المعلومات وفقًا للنموذج المحدد

الأسبوع التاسع: إنهاء بنية التوثيق الرئيسية والصفحات بعد نقل جميع المشاريع الفرعية لبرنامج التتبُّع

الأسبوع 10: التحقّق من إعدادات JSDoc حدِّد مكانًا لتخزين عناصر JSDoc. ابدأ بتوثيق طرق تشغيل برنامج التشغيل.

الأسبوع 11: إنهاء توثيق طرق برنامج التشغيل

الأسبوع 12: تقييم النتائج

تفاصيل الإنجازات

مدة مراجعة الطلب

سيتم تخصيص الجزء الأول من هذه الفترة للتحقّق من قنوات المنتدى ورمز المصدر والتواصل مع الأشخاص الملتزمين بالمشروع.

سيتم تخصيص الجزء الثاني من هذه الفترة للتحقّق من ثقافة المساهمة بشكل عام، وفحص أدلة المساهمة وأفضل الممارسات. هذا هو الوقت المناسب للمساهمات الأولى لمعرفة طريقة سير العمل.

الشعور بالانتماء إلى منتدى

وسنخصّص هذه الفترة لفحص مستودع المستندات بشكل أعمق بالإضافة إلى خارطة الطريق الخاصة به. استنادًا إلى هذه المعلومات، سيكون من الممكن تحديد نقاط الضعف (مثل الأجزاء غير المكتملة أو غير المتوفّرة) التي يمكن تحسينها. أنشئ طلبات سحب (حيثما أمكن) لملء الفجوات.

الأسبوع 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)
    • التحدّث إلى برنامج التتبُّع في مقالة "إنشاء مستخدمي برامج التتبُّع" (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. التعريف

    تحديد قائمة بالمشاريع الفرعية للبوت التي يجب نقلها إلى المستندات الرئيسية حدِّد آلية عمل المواقع الإلكترونية للبرامج الآلية بعد عملية النقل (تتوفّر مواقع إلكترونية منفصلة تتضمّن مستندات بالإضافة إلى github لبعض البرامج الآلية، مثل bbot (http://bbot.chat)).

  2. نموذج

    تحديد نموذج (طريقة) وإنشاءه لتنظيم المعلومات ضمن المشاريع الفرعية للبوت المحدّدة في الخطوة الأولى قد يبدو هذا النموذج على النحو التالي:

    أ. استنساخ مستودع

    ب- تثبيت التبعيات

    ج. ضبط إعدادات روبوت

    د- تشغيل روبوت

    هـ- التهيئة المتقدمة

    و- خطوات إضافية

    يجب أن تكون الأوامر التي تتضمّن بعض النتائج المهمة (مثل "تشغيل روبوت") مصحوبة بعروض تقديمية مباشرة لهذه النتائج باستخدام أداة Term Sheets (https://neatsoftware.github.io/term-sheets/).

    بالإضافة إلى ذلك، لجعل مرحلة "البدء السريع" الأولية (الخطوات "أ" إلى "د") أكثر وضوحًا، سيتم أيضًا دمج جميع الخطوات في عرض تقديمي مباشر واحد.

    لمنح المستخدمين الجدد شعورًا بالأمان من الأعطال المحتمَلة، يجب توفير أمثلة على الرموز البرمجية مع بيئة "مساحة اللعب" (باستخدام Glitch، كجزء من منظومة Rocket Chat المتكاملة) حيث يمكن للمستخدمين الجدد التواصل مع برامج التتبُّع التي تستخدم ""مثال الرمز البرمجي"".

  3. الإعداد

    إعداد المستندات الرئيسية لعملية النقل. ويشمل ذلك إنشاء بنية المجلد والصفحة المناسبةَين، بالإضافة إلى تعديل جدول المحتويات وفقًا لهذه البنية.

    قد تبدو البنية النهائية على النحو التالي:

    • برامج التتبُّع
      • بنية برامج التتبُّع
      • إنشاء مستخدمي روبوت الدردشة
      • ضبط بيئة الروبوت
      • تشغيل برامج التتبُّع
        • روبوت bBot
        • روبوت Hubot
        • روبوت Botkit
        • راسا بوت
        • روبوت Botpress

  4. النقل

    نقل المشاريع الفرعية لبرنامج التتبُّع إلى الوثائق الرئيسية واحدًا تلو الآخر. ستتضمّن كل قطعة من مستندات الروبوت صفحة منفصلة تتضمّن أقسامًا فرعية مثل الإصدار الحالي (مثل تشغيل bBot).

    • تشغيل برامج التتبُّع
      • روبوت bBot
      • روبوت Hubot
      • روبوت Botkit
      • راسا بوت
      • روبوت Botpress

  5. المؤسسة

    ستكون هناك عدة أنشطة:

    1. تنظيم المعلومات من كل مستودع github للبوت وفقًا للنموذج المحدّد في الخطوة الثانية
    2. نقل المكوّنات الشائعة (مثل المتغيّرات البيئية) المرتبطة بجميع المشاريع الفرعية للبوت إلى مستوى أعلى في التدرّج الهرمي للمستندات الرئيسية وربط المشاريع الفرعية للبوت بهذه المكوّنات
    3. إنشاء مثال على روبوت الدردشة "hello world" لكل إطار عمل متوافق. سيتم استخدام هذا المثال كبوت "للبدء" في Rocket.Chat.

ما سبب أهمية هذا؟ تتضمّن جميع المشاريع الفرعية الثمانية المتوافقة مع Rocket.Chat، وهي alexa وhubot وchatops-gitsy وbotpress وrasa وbbot وbotkit وBOTswana وhubot-gitsy، مستندات متناثرة في شكل ملفات README للمطوّرين. لا تتضمّن ملفات 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-methods) والتي يجب تعديلها بشكل منفصل عند إجراء أي تغيير في طرق حِزم تطوير البرامج (SDK).

الأسبوع 11

سيتم تخصيص هذا الأسبوع بالكامل لوضع اللمسات الأخيرة على وصف طرق السائقين. وبعد اكتمالها، سيتم اختبار الأوصاف للتأكّد من دقتها واتّساقها، وسيتم بعد ذلك نشر الوثائق الجديدة في جميع أنحاء العالم.

الأسبوع 12

إنهاء العمل المكتمل عمليات التحقّق من القبول.