تحتوي هذه الصفحة على تفاصيل مشروع كتابة تقنيّة تم قبوله في موسم المستندات من Google.
ملخص المشروع
- المؤسسة المفتوحة المصدر:
- gRPC-بوابة
- الكاتب التقني:
- إيامراجيف
- اسم المشروع:
- إعادة بناء موقع "مستندات 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.
لماذا أنا الشخص المناسب لهذا المشروع:
أعتقد أنني الشخص المناسب لهذا المشروع لأن:
• لدي خبرة سابقة في تحسين وثائق المؤسسات ويمكنني استخدام أي نظام للتحكم في الإصدار، لذا لن يمثل تنفيذ الأوامر على جيت هب أي مشكلة. • علاوة على ذلك، فإن ما يدفعني هو العمل على مشروعات تخلق قيمة للأشخاص. أعتقد أنه إذا كنت تريد أن يقوم شخص ما بشيء ما بأكثر الطرق فعالية ممكنة، فعليك توثيقه. من خلال توثيق عملياتك، فإنك تضمن الكفاءة والاتساق وراحة البال لأي شخص مشارك. • لديّ دراية بسير العمل وقاعدة رموز gRPC-Gateway لأنّني أساهم في gRPC-Gateway منذ الشهرين الماضيين ودمجتُ 11 قسمًا عامًا.