تحتوي هذه الصفحة على تفاصيل مشروع كتابة فنية تم قبوله في "موسم مستندات Google".
ملخّص المشروع
- مؤسسة مفتوحة المصدر:
- Cloud Native Computing Foundation (CNCF)
- الكاتب الفني:
- شريتي
- اسم المشروع:
- تحسين مستندات SMI وشبكات الخدمات ذات الصلة
- مدة المشروع:
- المدة العادية (3 أشهر)
وصف المشروع
تهدف تقنية "شبكة الخدمات" بشكل أساسي إلى توفير قيمة للعدد المتزايد من الخدمات، من خلال معالجة جميع احتياجاتك المتعلقة بالأمان والإدارة والتتبّع. تحدِّد واجهة Service Mesh Interface (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" ودليل مستخدم مستقل بمساعدة Jekyll ودمجها في النهاية مع وثائق واجهة برمجة التطبيقات لمنح كل من المستخدم النهائي والمتعاونين في المستقبل تجربة شاملة.
الجمهور المستهدَف: توفّر مشاريع SMI ممارسات التشغيل والنشر وبيئات التعلّم ومقاييس الأداء لجميع المشاريع التي تندرج تحتها. وهو يناسب كلّ من الأفراد والمؤسسات.
أدلة المستخدم: سأستهدف مستخدمين مبتدئين، بدون افتراضات بمعرفة تكنولوجيا المعلومات الموجودة مسبقًا من جانب المستخدم. الاستهداف: المستخدمون للمبتدئين السبب: يُستخدم بشكل أساسي كدليل مرجعي كبير، ويجب تحديثه بمرور الوقت. وسيتضمّن ذلك شرحًا مفصّلاً ونصائح مفيدة للتأكّد من حصول المستخدم على كل المعلومات التي يحتاجها لإعداد شبكة الخدمات والعمل بها. سنعمل على تحسين الدليل وجعله أكثر تفاعلاً وسهولة في الاستخدام من خلال إضافة فيديوهات وصور ولقطات شاشة وملفات GIF عند الحاجة.
أدلة المستخدمين الإرشادية: الهدف: المستخدمون المبتدئون السبب: سيتم التركيز على جعل الأدلة الإرشادية جذابة من الناحية الجمالية وتفاعلية لجذب انتباه المستخدم والسماح بإجراء اختبار سلس للبرنامج، ما سيؤدي إلى فهم أفضل لواجهة Service Mesh.
مستندات نقاط نهاية واجهة برمجة التطبيقات: الهدف: المستخدمون المتقدّمون السبب: يركز هذا القسم على استخدام الميزات الأكثر تعقيدًا لشبكة الخدمات، والتي تهمّ المستخدمين المتقدّمين الذين لديهم مستوى أساسي من المعرفة بتكنولوجيا المعلومات. سيبحث المستخدمون المتقدّمون عن دروس موجزة يمكن استخدامها أيضًا كأدلة مرجعية، إذا لزم الأمر. يجب كتابة وثائق نقاط النهاية بطريقة تجعل من السهل تعديلها بدون المساس بدقتها أو اتساقها. من الأفضل أن تكون هذه العملية مبرمَجة.
المراجع: الأدلة التعليمية للمستخدمين: دروس Google Developers Codelab: تُستخدَم لإنشاء أدلة تعليمية تفاعلية وشاملة للمستخدمين النهائيين. الفوائد: - يمكن أن تنتج برامج تعليمية لوضع الحماية. - أن يتّبع أسلوبًا عمليًا - أن تكون مكتوبة باستخدام "مستندات Google" وأن تتيح استخدام نص Markdown - يمكن رصدها باستخدام "إحصاءات Google" - من السهل مراقبة زيارات المستخدمين. - سهولة الاستخدام توفر برامج تعليمية مُرضية من الناحية الجمالية تسمح للمستخدم بالتفاعل مباشرة مع البرنامج دون أي استثمار مباشر.
يمكن تحسين "برامج Google Codelabs" ونشرها بسهولة باستخدام مشروع CLaaT (Codelabs as a Thing)، وهو برنامج يوفّر أداة سطر أوامر تُستخدَم لتحويل الأدلة التعليمية المكتوبة في "مستندات Google" باستخدام Markdown إلى تنسيق codelabs (HTML).
أدلة المستخدم: Jekyll: يمكن العثور على المستندات الحالية الخاصة بخدمة meshery.io هنا، وهي مستضافة على Jekyll وتستخدم مظهر Docsy Jekyll. ويستخدم Markdown وLiquid وHTML وCSS لإنشاء مواقع إلكترونية ثابتة جاهزة للاستضافة، ويتم تشغيله في بيئة تطوير Ruby. المزايا: - يمكن استضافة المواقع الإلكترونية مباشرةً من مستودعات GitHub. - هذا مشروع مدعوم جيدًا ولديه منتدى نشط جدًا - يمكن إضافة أدلة المستخدمين والتحسينات بسهولة إلى مستندات 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 مع تطبيق bookinfo وConsul من Hashicorp. لقد جرّبت أيضًا تقسيم عدد الزيارات عبر بروتوكول SMI ونفّذتُ قواعد تحقُّق مختلفة على إعدادات الشبكة المتداخلة للخدمة. إنّ عملية التعلّم مثيرة للاهتمام ولكنها فنية للغاية ويمكن أن تكون مزعجة للمستخدمين الجدد والمطوّرين الذين يريدون اتّخاذ خطواتهم الأولى في منتدى شبكة الخدمات أو استخدام شبكات الخدمات لمشاريعهم الشخصية أو المهنية. أريد سدّ هذه الفجوة، ولا يمكنني فعل ذلك إلا من خلال الدلائل والأدلة التعليمية الفعّالة والموثَّقة جيدًا.