مشروع Rocket.Chat

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

ملخص المشروع

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

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

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

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

الترابط بين أفراد المنتدى: استكشاف المنتدى افحص الحالة الحالية لمستندات برنامج التتبُّع. تحديد نقاط الضعف.

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

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

الأسبوع 3- تحديد قائمة بالمشروعات الفرعية (bot github repos) التي يجب نقلها إلى الوثائق الرئيسية. - تحديد آلية عمل برامج التتبّع على الويب بعد عملية النقل - تحديد قالب سيتم استخدامه لتنظيم المعلومات داخل هذه المستودعات. - إعداد المستندات الرئيسية لعملية النقل

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

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

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

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

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

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

الأسبوع 10: تحقق من تهيئة JSDoc. تحديد مكان لتخزين عناصر JSDoc. بدء توثيق طرق القيادة

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

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

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

فترة مراجعة الطلب

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

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

توطيد العلاقات مع أفراد المنتدى

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

الأسبوع 1 - الأسبوع 2

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

وسيكون الأسبوع الثاني حول إنشاء محتوى للصفحة الرئيسية الجديدة لبرامج التتبُّع وفقًا للرؤية ومراجعة نظرة عامة على برامج التتبُّع وبنيةها وإعدادات إعداداتها.

ستركّز المستندات المعدَّلة بشكل أوضح على ما يلي: - المطوّرون الجدد الذين يريدون إنشاء برامج تتبُّع خاصة بهم - مطوّرو [برامج التتبُّع] المحترفين الذين يريدون تصميم برامج التتبُّع الخاصة بهم أو ترميزها أو اختبارها باستخدام منصة مجانية وسهلة الاستخدام أو التكيّف مع برامج التتبُّع الحالية مع ذلك النظام الأساسي - مطوّرو برامج التتبُّع الحاليون الذين لديهم تفضيلات لأُطر عملهم ويريدون إنشاء برامج تتبُّع لتطبيق Rocket.Chat

سيكون نطاق العمل على النحو التالي:

  1. يُرجى إزالة الأقسام المكرّرة. على سبيل المثال، تشترك الأقسام التالية في معلومات متداخلة:
    • كيف ترسل برامج التتبُّع الرسائل وتستلمها؟ في "نظرة عامة على برامج التتبُّع" (https://rocket.chat/docs/bots/#how-do-bots-send-and-begin-messages)
    • ساحات مشاركات الرسائل في بنية برامج التتبُّع (https://rocket.chat/docs/bots/bots-rcitecture/#message-streams)
    • تحدَّث إلى برنامج التتبُّع عن "إنشاء مستخدمي برامج التتبُّع" (https://rocket.chat/docs/bots/setting-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. النموذج

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

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

    b. تثبيت التبعيات

    ج- ضبط برنامج تتبُّع

    د- تشغيل برنامج تتبُّع

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

    f. خطوات إضافية

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

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

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

  3. الإعداد

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

    قد يبدو الهيكل النهائي كما يلي:

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

  4. النقل

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

    • تشغيل برامج التتبُّع
      • برنامج تتبع bBot
      • Hubot Bot
      • روبوت Botkit
      • راسا بوت
      • برنامج تتبُّع الضغط

  5. مؤسسة

    سيكون هناك العديد من الأنشطة:

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

ما سبب أهمية هذا؟ تشتمل جميع المشاريع الفرعية الثمانية التي يدعمها Rocket.Chat: alexa وHubot وchatops-gitsy وbotpress وrasa وbbot وbotkit وBOTswana وHubot-gitsy على مستندات مبعثرة على شكل تطبيقات للمطوّرين READMEs. لا تحتوي هذه السجلات على أي هيكل على الإطلاق، أو تحتوي على معلومات قديمة حول كيفية البدء، أو تحتوي على الكثير من المعلومات (في بعض الأحيان يتم استخدام التكرار الثلاثي، مثل 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

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