تحتوي هذه الصفحة على تفاصيل مشروع كتابة تقنيّة تم قبوله في موسم المستندات من Google.
ملخص المشروع
- المؤسسة المفتوحة المصدر:
- Cloud Native Computing Foundation (CNCF)
- الكاتب التقني:
- الضريحي
- اسم المشروع:
- تحسين مستندات SMI وشبكات الخدمات ذات الصلة
- مدة المشروع:
- المدة العادية (3 أشهر)
وصف المشروع
تهدف Service Mesh Technology بشكل أساسي إلى تقديم قيمة إضافية للعدد المتزايد من الخدمات، من خلال تلبية جميع احتياجاتك المتعلّقة بالأمان والإدارة والمراقبة. تحدد \"واجهة الشبكة المتداخلة (SMI)" مجموعة من واجهات برمجة التطبيقات لحالات استخدام شبكة الخدمة الأكثر شيوعًا (سياسة حركة المرور، وقياس الأداء عن بُعد، والتبديل) وتفعّل التوافق بين شبكات الخدمة، وهي طبقات بنية أساسية مخصّصة للتعامل مع الاتصال بين الخدمات في بيئة الخدمات المصغّرة. سيوفّر توحيد هذه الواجهات تجربة أفضل للمستخدم، وبالتالي سيكون هدفًا مستقبليًا لمؤسسات SMI وشبكات الخدمات ذات الصلة.
الحالة الحالية:
أدلة المستخدم: SMI هو مشروع وضع حماية جديد نسبيًا وقد تم التبرع به إلى CNCF في أبريل 2020. ونتيجة لذلك، يفتقر المشروع إلى وثائق المستخدم. Meshery هي منصة لإدارة الخدمات تتضمّن مقاييس أداء لجميع أنواع الخدمات التي تسهّل استخدام شبكات الخدمة المختلفة وإعدادها وتشغيلها وإدارتها، وتتضمّن جمع وعرض المقاييس من التطبيقات التي تعمل فوق أي شبكة خدمة. وبالتالي، أود أن أبدأ بدليل Meshery، والذي سيكون بمثابة نقطة انطلاق لمجتمع مستخدمي SMI بأكمله.
البرامج التعليمية للمستخدم: من بين منصات SMI الحالية: يُستخدم نموذج التطبيق، Learn Layer5، حاليًا كجهاز تعليمي لمنهجية SMI وكتطبيق نموذجي يمكن استخدامه للتحقّق من مواصفات SMI وفقًا له.ولكن بخلاف ذلك، تفتقر مشاريع SMI إلى البرامج التعليمية للمستخدم النهائي، وهو ما يشكّل عائقًا خطيرًا بسبب الطبيعة التقنية العالية للمشاريع. Meshery هو التطبيق المثالي لعرض مزايا واستخدام SMI وشبكات الخدمات ذات الصلة، ولهذا سأستخدمه كأداة أساسية لعرض ميزات SMI.
مستندات واجهة برمجة التطبيقات: غير متوفّرة في الوقت الحالي. يتم تحديد نقاط نهاية واجهة برمجة التطبيقات لدى SMI والمشروعات المتعددة ذات الصلة على أحد الأنظمة الأساسية. على سبيل المثال، يتم تحديد نقاط النهاية الخاصة بـ Meshery على الرابط server.go (https://github.com/layer5io/meshery/blob/master/router/server.go)، لكن لا يتم التعليق عليها أو توثيقها بشكل جيد خارجيًا. يمكن حل هذه المشكلة من خلال مستندات مفيدة حول واجهات برمجة التطبيقات، ويمكن تحسينها من خلال إضافة طرق تتيح للمستخدمين اختبار نقاط النهاية ومعاينة ميزاتها.
التحليل:
يتم إنشاء البرامج التعليمية للمستخدم للسماح للمستخدم بالتفاعل وإجراء اختبار تجريبي للبرامج. يجب أن تكون تفاعلية وجذابة من الناحية الجمالية لجذب انتباه المستخدم والأهم من ذلك، أن تكون سهلة الاستخدام.
ومع ذلك، بالنسبة إلى كتابة أدلة المستخدمين أو استضافتها، ننصح باستخدام تنسيق أكثر نضجًا، لأنّ أدلة المستخدم غالبًا ما تُستخدم كدليل مرجعي أو كوسيلة لحلّ المشاكل بسرعة. بدلاً من أن تكون تفاعلية، يجب أن تكون منظمة بشكل جيد والتركيز على تحسين الوضوح والتماسك والتدفق الجيد للمستخدم.
ويتمثل الحل الممكنة لذلك في إنشاء برامج تعليمية منفصلة للمستخدمين باستخدام Google Codelabs ودليل مستخدم مستقل بمساعدة Jekyll ودمجها في النهاية مع وثائق واجهة برمجة التطبيقات لتقديم تجربة شاملة لكل من المستخدم النهائي والمتعاونين في المستقبل.
الجمهور المستهدف: توفّر مشاريع SMI ممارسات النشر والتشغيل، وبيئات التعلُّم، ومقاييس الأداء لجميع المشاريع المندرجة ضمنها. وهي تلبي احتياجات الأفراد والمؤسسات.
أدلة المستخدم: سأستهدف المستخدمين المبتدئين، بدون افتراضات وجود معرفة سابقة بتقنية المعلومات لدى المستخدم. الاستهداف: المستخدمون المبتدئون السبب: يُستخدم بشكل أساسي كدليل مرجعي واسع، والذي يجب تحديثه بمرور الوقت. سيتضمن ذلك توضيحات متعمقة ونصائح مفيدة، للتأكد من أن المستخدم لديه جميع المعلومات التي يحتاج إليها لإعداد شبكة الخدمة المتداخلة والعمل عليها. سيصبح الدليل أكثر جاذبية وسهولة للاستخدام من خلال إضافة فيديوهات وصور ولقطات شاشة وملفات GIF كلما لزم الأمر.
برامج تعليمية للمستخدم: الهدف: المستخدمون المبتدئون السبب: سيكون التركيز على جعل البرامج التعليمية جذابة وجذابة من الناحية الجمالية لجذب انتباه المستخدم والسماح بتشغيل اختبار سلس للبرنامج، مما سيؤدي إلى فهم أفضل لواجهة Service Mesh.
مستندات نقطة نهاية واجهة برمجة التطبيقات: الهدف: المستخدمون المتقدمون السبب: يركز هذا القسم على استخدام الميزات الأكثر تعقيدًا لشبكة الخدمة المتداخلة، والتي تهم المستخدمين المتقدمين الذين يملكون معرفة أساسية في مجال تكنولوجيا المعلومات. سيبحث المستخدمون المتقدمون عن برامج تعليمية موجزة يمكن استخدامها أيضًا كأدلة مرجعية، إذا لزم الأمر. يجب كتابة مستندات نقطة النهاية بهذه الطريقة لتسهيل عملية التعديل بدون المساس بدقة أو اتساقها. ويفضَّل أن تكون هذه عملية تلقائية.
الموارد: البرامج التعليمية للمستخدمين: الدرس التطبيقي حول الترميز الخاص بـ Google Developers - يُستخدم لإنشاء برامج تعليمية تفاعلية وشاملة للمستخدمين النهائيين. الفوائد: - يمكن إنتاج برامج تعليمية في وضع الحماية. - لديه نهج عملي. - تتم كتابتها باستخدام "مستندات Google" وتدعم نص Markdown. - يمكن مراقبتها باستخدام Google Analytics - يسهل مراقبة حركة زيارات المستخدمين. - سهولة الاستخدام توفر دروسًا تعليمية مبهجة من الناحية الجمالية تتيح للمستخدم التفاعل مباشرةً مع البرنامج دون أي استثمار مباشر.
يمكن تحسين Google Codelabs ونشرها بسهولة باستخدام مشروع CLaaT (الدروس التطبيقية على شكل Thing)، وهو برنامج يوفّر أداة سطر أوامر تُستخدَم لتحويل البرامج التعليمية المكتوبة في "مستند Google" باستخدام Markdown إلى تنسيق الدروس التطبيقية (HTML).
أدلة المستخدم: Jekyll - تتم استضافة الوثائق الحالية لـ meshery.io، والتي يمكن العثور عليها هنا على Jekyll وتستخدم المظهر Docsy Jekyll. وهو يستخدم Markdown وسوائل وHTML وCSS لإنتاج مواقع ويب جاهزة للاستضافة ومواقع ويب ثابتة وتعمل على بيئة تطوير Ruby. المزايا: - إمكانية استضافة المواقع مباشرة من مستودعات جيت هب. - هذا المشروع متوفر بشكل جيد ويضم منتدى نشِطًا للغاية. - يمكن بسهولة إضافة أدلة المستخدم والتحسينات إلى مستندات SMI وMeshery الحالية، بدون الحاجة إلى الانتقال إلى منصة أخرى.
وثائق واجهة برمجة التطبيقات: سيتم استخدام Swagger (بدلاً من ذلك، Swaggo) لإنشاء وثائق واجهة برمجة التطبيقات لـ SMI وMeshery. وهو حل أنيق لكتابة مستندات واجهة برمجة التطبيقات. الفوائد: - وثائق من تصميم واجهة برمجة التطبيقات: تضمن تحديث مستنداتك باستمرار مع تطور واجهة برمجة التطبيقات. - وثائق من تصميم واجهة برمجة التطبيقات: يمكن إنشاؤها تلقائيًا من تعريفات واجهة برمجة التطبيقات. - الاحتفاظ بنُسخ متعددة من الوثائق - تصميمات واجهة برمجة التطبيقات المخصصة
أهداف المشروع: - استخدام Google Developer Codelabs لإنشاء برامج تعليمية تفاعلية للمستخدمين النهائيين حول SMI وشبكات الخدمات ذات الصلة باستخدام Meshery كأداة. - قم بإنشاء دليل المستخدم، باستخدام Jekyll لشبكات الخدمة. - استخدام Swagger لإنشاء وثائق نقطة نهاية واجهة برمجة التطبيقات من أجل SMI. - جعل منتدى المشروع موجهًا نحو تمكين المستخدمين أو المطورين في المستقبل والحاليين من الاستمرار في الإضافة إليه بسهولة تحت توجيه والإشراف من مجتمع SMI.
الجدول الزمني: يمكن الاطّلاع على المخطط الزمني المُقترَح هنا: https://docs.google.com/document/d/1If2mtBdWZer4qrh66NfXOWBx_3-tiA09jnoPMqy2lqs/edit#bookmark=kix.j1b6m64eubsl
البنية: يمكن العثور على الهيكل المقترح لدليل المستخدم هنا: https://docs.google.com/document/d/1A3YYAMUTe06MojNWo8hdF4KZbvr-qVaaA2myzWeshHQ/edit?usp=sharing
لماذا هذا المشروع؟ يتوسع مجتمع الخدمات المتداخلة بوتيرة سريعة للغاية، وذلك بفضل دمجه مؤخرًا كمشروع وضع حماية في CNCF. ومع ذلك، يشهد المشروع ندرة كبيرة من الوثائق، لكل من المستخدمين النهائيين والمطورين. لقد اختبرتُ العديد من شبكات الخدمات في الماضي، بما في ذلك linkerD مع تطبيق EmojiVoto، وIstio بتطبيق معلومات الكتب وقنصل Hashicorp’s Consul. لقد جرّبتُ أيضًا تقسيم عدد زيارات SMI ونفّذتُ قواعد مختلفة للتحقّق من صحة إعدادات الشبكة المتداخلة الخاصة بالخدمة. إنّ عملية التعلُّم رائعة ولكنّها تقنية للغاية ويمكن إبعادها عن المستخدمين الجدد والمطوّرين الذين يتطلّعون إلى اتّخاذ خطواتهم الأولى داخل مجتمع الخدمة المتداخلة أو استخدام الشبكات الخدمية في مشاريعهم الشخصية أو المهنية. وأود سد هذه الفجوة، التي لا يمكن القيام بها إلا باستخدام الأدلة والبرامج التعليمية الفعالة والموثَّقة جيدًا.