تحتوي هذه الصفحة على تفاصيل مشروع كتابة فنية تم قبوله في "موسم مستندات Google".
ملخّص المشروع
- مؤسسة مفتوحة المصدر:
- gRPC-Gateway
- الكاتب التقني:
- iamrajiv
- اسم المشروع:
- إعادة بناء موقع "مستندات Google" الحالي الخاص بـ gRPC-Gateway
- طول المشروع:
- المدة العادية (3 أشهر)
وصف المشروع
الملخّص:
تم تصميم موقع "مستندات المستخدم" الإلكتروني لمساعدة المستخدمين النهائيين على استخدام منتج أو خدمة. إنّ موقع المستندات الخاص بالمستخدمين مهم جدًا لأنّه يقدّم للمستخدمين طريقة لمعرفة كيفية استخدام البرنامج وميزاته ونصائحه وحيل استخدامه، كما يساعدهم في حلّ المشاكل الشائعة التي يواجهونها عند استخدام البرنامج. ويؤدي ذلك أيضًا إلى تقليل تكلفة الدعم، كما أنّه يشكّل جزءًا من هوية الشركة للمنتج. إنّ الموقع الإلكتروني الجيد لمستندات المستخدمين هو علامة على صحة المنتج وفريق المطوّرين. فبدون موقع إلكتروني جيد لمستندات المستخدمين، قد لا يعرف المستخدم كيفية تنفيذ المهام المذكورة أعلاه بفعالية وكفاءة. يمكن أن يلعب موقع مستندات المستخدمين دورًا محوريًا في ضمان نجاح المنتج، لأنّ التواصل الجيد هو أساس أي نشاط تجاري أو منتج، وسيظل كذلك دائمًا، وتعمل المستندات الجيدة على تحويل هذا التواصل إلى إطار عمل يمكن للجميع الوصول إليه لتحقيق النجاح.
في وقت كتابة هذا التقرير، تم تشعب مستودع gRPC-Gateway حوالي 1200 مرة وساهم 184 شخصًا في هذا المستودع وهذا يوضح أن الكثير من الأشخاص في جميع أنحاء العالم يستخدمون gRPC-Gateway وقد يرغبون في قراءة وثائق المستخدم للحصول على إرشادات حول كيفية استخدام gRPC-Gateway. ومع ذلك، فإن موقع مستندات ووثائق مستخدمي gRPC-Gateway قديم وغير مكتمل حاليًا ويريد منتدى gRPC-Gateway استخدام هذا المشروع لإعادة ضبط موقع المستندات الحالي على تحسين موقع المستندات التابع له لتمكين المستخدمين النهائيين من الحصول على تجربة سلسة عند استخدام gRPC-Gateway.
الحالة الحالية:
في الوقت الحالي، هناك مشكلتان رئيسيتان في موقع مستندات gRPC-Gateway:-
• المشكلة الأولى هي موقع الويب الخاص بالوثائق الذي يتصف بالسوء والقدم، أي أنّ التصميم وبنية الموقع والمظهر المستخدَم قديمان وغير مكتملان، ومن الصعب التنقّل فيهما أو العثور على المعلومات، ولا يشملان العديد من ميزات موقع الويب الجيد للوثائق. تشمل إعادة تصميم موقع المستندات الحالي لـ gRPC-Gateway تصميم الموقع الإلكتروني، وإضافة ميزات مثل البحث في المستندات وما إلى ذلك، وتحسين واجهة المستخدم لموقع الويب، وتنظيم البرامج التعليمية والأمثلة في شريط جانبي مناسب، وتحديث المخططات الانسيابية والصور من خلال تصميم موقع جديد وما إلى ذلك. وسيكون هذا هدفي الأساسي وسيستند عملي بشكل أكبر إلى تصميم وإعادة هيكلة موقع المستندات الحالي.
• المشكلة الثانية، هناك حاجة إلى إعادة ضبط الوثائق والبرامج التعليمية والأمثلة الحالية وغيرها من بوابة gRPC-Gateway، والتي يمكن إجراؤها من خلال إزالة الأخطاء المطبعية والنحوية في الملفات، وضمان محاذاة مقتطفات Go بشكل مناسب وإعادة ضبط مقتطفات Go وفقًا لتنسيقات Gofmt. في هذه الحالة، يمكننا إضافة المزيد من المستندات والأدلة التعليمية والأمثلة إذا لزم الأمر، أو يمكننا إعادة استخدام الملفات الحالية بعد إعادة تنظيمها. هذا هو هدفي الثانوي وسأنفّذه بعد إكمال هدفي الأساسي، أي تصميم موقع "مستندات Google" الحالي وإعادة تنظيمه.
لماذا يحقّق موقع "مستنداتي" المقترَح تحسّنًا مقارنةً بالموقع الحالي؟
سيتم تصميم الموقع الإلكتروني المُقترَح لمستندات المستخدمين بهدف تحسين وضمان الكفاءة والاتساق وراحة البال للمستخدم النهائي. سيمنح ذلك مظهرًا وواجهة مستخدم أفضل مع أقسام وميزات منمّقة جيدًا تحتوي على أدلة مكتوبة ومخططات تدفق وصور مرتبطة بها.
تقدّم مستندات gRPC-Gateway وصفًا جيدًا للطريقة والمثال. لا يزال يستخدم مظهر Jekyll القديم، ولكن في الوقت الحالي، لدينا مظاهر Jekyll أفضل لإنشاء المواقع الإلكترونية الثابتة (SSG). هناك أيضًا حاجة إلى إعادة تنظيم الصفحات وجعلها أكثر فائدة للمستخدمين من خلال إضافة أمثلة وأدلة تعليمية جديدة وتعديل المحتوى السابق وإعادة كتابته.
بنية الأهداف والأفكار المقترَحة وخارطة الطريق الخاصة بها:
الهدف الأساسي لهذا المشروع:
يمكن تنفيذ الأهداف والأفكار المذكورة أعلاه بالطرق التالية:-
تغيير المظهر الحالي في Jekyll إلى مظهر أفضل وأكثر كفاءة يرجع سبب استخدام مظاهر Jekyll مرة أخرى إلى أنّه سيكون من السهل على القائمين بالصيانة المساهمة في سير عمل المشروع وفهمه، لأنّهم على دراية بإطار عمل Jekyll الحالي ومظهره الذي يشبه مظهر Jekyll الجديد.
بعد مراجعة مواضيع Jekyll المختلفة على الإنترنت، وجدتُ أنّ مجموعة المظاهر https://idratherbewriting.com/documentation-theme-jekyll/ هي الأفضل لموقع مستندات gRPC-Gateway الإلكتروني بسبب الميزة التالية:
• Markdown:- لكي لا يقلق الكتاب الفنيون بشأن عملية التثبيت. ويمكنهم الكتابة ببساطة في ملف .md. يمكن لأي مستخدم النقر على زر التعديل المعروض على الموقع الإلكتروني (ميزة جديدة) والمساهمة (تعديل/اقتراح تغييرات للصفحة في GitHub) لتحسينها. سيؤدي ذلك إلى حثّ المستخدمين على إضافة محتوى جديد أو تعديل المحتوى لتحسينه.
• البحث في الوثائق:- يجب أن يتوفر لدى المستخدم مربع بحث ليتمكن من العثور على المحتويات ذات الصلة بسهولة وسرعة.
• قسم التعليقات:- قد يتوفّر للمستخدم خيار التعليق ومشاركة آرائه حول المشاركات والأدلة التعليمية. يمكنهم قراءة آراء المستخدمين الآخرين حول مستندات المشروع.
• ملاحظات الإصدار الجديدة والمدوّنات:- يجب تعديل الموقع الإلكتروني من خلال إضافة مشاركات مدوّنة جديدة وأخبار حول التطوير الحالي وخارطة الطريق. لذا، يجب أن يكون هذا النوع من التدوين متوفّرًا على الصفحة المقصودة.
• التطوير السريع:- يتم تشغيل معظم إطارات عمل SSG (أداة إنشاء المواقع الإلكترونية الثابتة) في الخادم، وتتم إعادة عرض التغييرات في الملف على واجهة المستخدم على الفور. يجب أن تكون عملية النشر والإنشاء سهلة أيضًا. في المستقبل، إذا أردنا تغيير الإطار، سنستخدم من المفترض أن يكون الأمر سهلاً. تتوافق معظم الإطارات مع كتابة Markdown، لذا يكفي نقل ملفات .md وإجراء بعض التغييرات.
سأقسّم هنا صفحات الموقع الإلكتروني الحالية إلى أقسام وصفحات جديدة للموقع الإلكتروني :
• الصفحة المقصودة:-
ينبغي أن تشير الصفحة المقصودة إلى الميزات الرئيسية لـ gRPC-Gateway.
- بدء استخدام gRPC-Gateway (إعادة التوجيه إلى دليل المستخدم)
- تعليمات التثبيت البسيطة (أوامر موجزة)
- لماذا نستخدم gRPC-Gateway
- المشروع باستخدام gRPC-Gateway
لذا فالفكرة الأساسية هي بدلاً من كتابة وصف طويل، أن تعرض النقاط الرئيسية في الصفحة المقصودة وتقدم رابطًا للانتقال إلى التفاصيل.
• صفحة دليل مستخدم gRPC-Gateway:-
- دليل التركيب
- بدء سريع باستخدام gRPC-Gateway
• صفحة دليل مطوّري gRPC-Gateway:-
يشير دليل التطوير ودليل المساهمة وإعداد Git ورمز السلوك وإعداد المستندات وسير عمل التطوير وما إلى ذلك إلى صفحات مشابهة داخل الدليل. لذا، هناك حاجة إلى إعادة ضبط جميع الملفات وإعادة ترتيبها. يجب أن تحتوي صفحة التطوير الرئيسية على كل هذه الصفحات وسيتم إنشاء الرابط التشعّبي في كل خطوة.
• لمحة عن صفحة gRPC-Gateway:-
يجب أن تتوفّر قائمة بجميع المساهمين في أقسام الفريق. سيتم إضافة روابط سريعة وملاحظات الإصدار وأحدث المقالات إلى القسم لجذب المستخدمين إلى قراءة أخبار gRPC-Gateway الحالية.
• صفحة المدونات وملاحظات الإصدار والبرامج التعليمية:-
أعتقد أنّ الموقع الإلكتروني يجب أن يتضمّن خيار نشر مدوّنات. وبالتالي يمكن توصيل الأخبار والإصدارات بسهولة. ستتضمّن صفحة البرنامج التعليمي بعض المحادثات والمقالات الرائجة التي توضّح واجهات برمجة التطبيقات ومبادئ gRPC-Gateway. يمكن للمساهمين إضافة روابط الأدلة التعليمية في صفحة الدليل التعليمي.
بعد إكمال المهمة أعلاه، عدِّل التغييرات نفسها في الفرع v2 وطبِّقها على الفرع الرئيسي من gRPC-Gateway.
الهدف الثانوي لهذا المشروع:-
يلزم إجراء تغييرات أخرى لجعل وثائق gRPC-Gateway أكثر قوة وقابلية للقراءة:-
• إصلاح الأخطاء النحوية والإملائية وتنظيم الروابط والمشاركات في الموقع الإلكتروني ومحاذاة هذه الروابط والمشاركات في جميع الملفات الحالية من gRPC-Gateway
• إضافة المزيد من الوثائق والمحتوى إذا لزم الأمر في gRPC-Gateway لأنّ معظم الميزات تحتوي على مستندات قصيرة جدًا، مثل قسم "المستندات" في الموقع الإلكتروني على AWS والخلفية والاستخدام وما إلى ذلك.
• إعادة صياغة مقتطفات Go gRPC-Gateway وفقًا لتنسيقات Gofmt
بعد إكمال المهمة أعلاه، عدِّل التغييرات نفسها في الفرع v2 وطبِّقها على الفرع الرئيسي من gRPC-Gateway.
سبب اختياري لهذا المشروع:
أعتقد أنني الشخص المناسب لهذا المشروع للأسباب التالية:
• لديّ خبرة سابقة في تحسين مستندات المؤسسات ويمكنني استخدام أي نظام تحكّم في الإصدارات، لذا لن تكون هناك مشكلة في تنفيذ الأوامر على GitHub. • بالإضافة إلى ذلك، شغفي هو العمل على مشاريع تضيف قيمة للمستخدمين. أعتقد أنّه إذا أردت من أحد الأشخاص تنفيذ مهمة ما بأكبر قدر ممكن من الكفاءة، عليك توثيقها. من خلال توثيق عملياتك، يمكنك ضمان الكفاءة والاتساق وراحة البال لأي شخص معنيّ. • أنا على دراية بعملية سير العمل وقاعدة بيانات gRPC-Gateway لأنّني أساهم في gRPC-Gateway منذ الشهرَين الماضيَين وتم دمج 11 طلب ربط.