تحتوي هذه الصفحة على تفاصيل مشروع كتابة فنية تم قبوله في "موسم مستندات Google".
ملخّص المشروع
- مؤسسة مفتوحة المصدر:
- Electron
- الكاتب الفني:
- Mister Gold
- اسم المشروع:
- مسار البرنامج التعليمي الإلكتروني
- طول المشروع:
- المدة العادية (3 أشهر)
وصف المشروع
ملخّص المشروع
إنّ Electron هي إحدى الأدوات الأكثر شيوعًا لإنشاء تطبيقات سطح المكتب المتوافقة مع جميع الأنظمة الأساسية باستخدام JavaScript وHTML وCSS. تتضمّن مجموعة التطبيقات المبنية على Electron ما يقرب من 900 إدخال، وتزداد هذه القائمة باستمرار. تم تصميم بعض أدوات المطوّرين الأكثر رواجًا، مثل Visual Studio Code وAtom وPostman وSlack وGitKraken باستخدام Electron.
تعود شعبية Electron إلى منحنى التعلّم البسيط والحد الأدنى المنخفض للدخول، إذ يمكن لأي شخص يعرف JavaScript وHTML وCSS إنشاء تطبيقه الخاص. تفرض معدلات النمو الإجمالية الضخمة الحاجة إلى إنشاء فيديوهات تعليمية وأدلة بدء الاستخدام التي يسهل فهمها واستخدامها.
يهدف المشروع إلى منح أدوات ثقة لصنّاع التطبيقات الذين بدأوا للتو استخدام إطار عمل Electron، وتزويدهم بتجربة متّسقة ومبسّطة لتطوير تطبيقات Electron الخاصة بهم من الصفر.
مشاكل المشروع
في ما يلي قائمة بالمشاكل الأكثر أهمية في ما يتعلّق بمستندات الدروس حول Electron: 1. نقطة بداية غير واضحة ومعلومات تمهيدية غير واضحة حول خطوات تطوير التطبيق 2. معلومات متناثرة ومتكرّرة حول عملية تطوير التطبيق 3. أجزاء غير منظمة من تعليمات "البدء" مع عدم وجود مصدر واحد للحقيقة
مقترح المشروع
وفقًا لهدف المشروع والمشاكل الموضّحة أعلاه، في ما يلي قائمة بالتحسينات المقترَحة: 1. تعديل الأدلة الحالية لتسهيل الخطوات الأولى وجعلها متسقة، يجب تعديل المستندات التالية من خلال التبديل التدريجي من الخطوات البسيطة إلى الخطوات الأكثر تعقيدًا: - بيئة المطوّر - كتابة تطبيقك الأول باستخدام Electron - إضافة ميزات إلى تطبيقك (إنشاء صفحة تلخيصية) - حزم التطبيقات وتوزيعها 2. إعادة تنظيم دليل المستندات لتعريف المطوّرين الجدد على الخطوات الأساسية للبدء والخطوات الإضافية التي يمكن اتّخاذها، يجب أن تتضمّن صفحة المستندات تقسيمًا مرئيًا وسياقيًا للخطوات من أجل نشر التطبيق الأول في أسرع وقت ممكن. تتضمّن عملية إعادة التنظيم أيضًا إرشادات حول الخطوات التالية المحتملة. 3- تنظيم مستندات تطوير التطبيقات وتوحيدها يجب أن تتضمّن جميع الميزات مجموعة موحّدة من التعليمات حول كيفية تثبيتها أو تفعيلها، وكيفية البدء بسرعة، وكيفية استخدام التطبيق بعد تشغيله لأول مرة، وكيفية توزيعه. 4. ضمِّن مستودع واجهة برمجة التطبيقات الإلكترونية في الوثائق. يحتوي مستودع إلكترون API-demos على مجموعة من الأمثلة التي توضح كيفية إضافة ميزات إلى تطبيق Electron الخاص بك. يجب تضمين هذه المعلومات في دليل "إضافة ميزات إلى تطبيقك" لتتلاءم مع استراتيجية المحتوى التي تستند إلى مصدر واحد للحقائق. 5- دمج أمثلة Electron Fiddle في المستندات ستسهّل هذه الخطوة على المطوّرين الجدد معرفة كيفية عمل رمز معيّن بدون الحاجة إلى تكرار الخطوات يدويًا. يتضمن الدمج كتابة عينات من التعليمات البرمجية للبرامج التعليمية المحدثة وإضافة زر "Launch in Fiddle" إلى كتل التعليمات البرمجية.
مجريات المباراة
فترة مراجعة الطلبات: يمكنك التعرّف على المنتدى والأشخاص الذين ستتعاون معهم. اطّلِع على أدلة أفضل الممارسات المتعلقة بالمساهمة في المنتدى. تقديم المساهمات الأولى الترابط بين أفراد المنتدى: استكشاف المنتدى تحقَّق من الحالة الحالية لوثائق Electron. تحديد نقاط الضعف الأسبوع الأول: التوافق مع المرشدين بشأن المعالم الرئيسية للمشروع والنتائج المرجوة الأسبوع الثاني: مراجعة بيئة المطوّر وكتابة صفحات تطبيقك الأول باستخدام Electron الأسبوع الثالث: مراجعة بنية التطبيق وإضافة ميزات إلى تطبيقك وصفحات حزم التطبيقات وتوزيعها إنشاء صفحة ملخص تحتوي على قائمة بالميزات التي يمكن إضافتها إلى التطبيق الأسبوع 4 - إعادة هيكلة دليل الوثائق الأسبوع 5 - إعداد قالب لكيفية دمج Electron-api-demos في الوثائق الرئيسية الأسبوع 6 - 7 - نقل مستودع Electron-api-demos الأسبوع 8 - إعداد نموذج لكيفية دمج Electron Fiddle اكتب العيّنة الأولى. الأسبوع 9 - 10 - دمج Electron Fiddle في الوثائق الرئيسية الأسبوع 11 - الانتهاء من بنية الوثائق الرئيسية والصفحات بعد ترحيل مستودع إلكترون API-demos وعينات إلكترون Fiddle الأسبوع 12 - تقييم النتائج
تفاصيل الإنجازات
فترة مراجعة طلب الانضمام سيتم تخصيص الجزء الأول من هذه الفترة للتحقّق من قنوات المنتدى ورمز المصدر والتواصل مع الأشخاص المعنيين بالمشروع.
وسيتم تخصيص الجزء الثاني من الفترة للاطّلاع على ثقافة المساهمات بشكل عام، والاطّلاع على أدلّة المساهمات وأفضل الممارسات المتعلّقة بها. سيكون هذا هو الوقت المناسب لتقديم المساهمات الأولى لمعرفة آلية عمل هذه العملية.
الشعور بالانتماء إلى منتدى
سيتم تخصيص هذه المرة لفحص مجلد المستندات بشكل أعمق بالإضافة إلى خارطة الطريق الخاصة به. استنادًا إلى هذه المعلومات، سيكون من الممكن تحديد نقاط الضعف (مثل الأجزاء غير المكتملة أو غير المتوفّرة) التي يمكن تحسينها. إنشاء طلبات سحب (حيثما أمكن) لملء الفجوات.
الأسبوع 1 - الأسبوع 2
سيتم تخصيص الأسبوع الأول للتواصل مع المرشدين من أجل التوافق مع المعالم المتوقعة وتسليمها في الوقت المناسب.
سيتناول الأسبوع الثاني مراجعة صفحتَي "بيئة المطوّر" و"كتابة أول تطبيق Electron". بالنسبة إلى صفحة "بيئة المطوّر"، سيتضمّن ذلك إعادة كتابة النظرة العامة العامة ومراجعة الأخطاء. بالنسبة إلى صفحة Write Your First Electron App، ستتضمن الصفحة جعل الصفحة دليلاً مفصلاً متسقًا مع نقطتي بداية ونهاية واضحتين وإزالة المعلومات المكررة (مثل كتلتين متشابهتين من الرموز ضمن قسم Electron Development بطريقة Nutshell و"تجربة هذا المثال").
التسليمات: أدلة مقدمة منقحة وسهلة المتابعة حول كيفية البدء السريع في استخدام تطبيقات Electron.
الأسبوع 3
سيتم تخصيص هذا الأسبوع لإجراء ما يلي: 1. تحسينات على صفحة "بنية التطبيق" ويشمل ذلك ما يلي: - إعادة كتابة المعلومات الحالية في قسم "العمليات الرئيسية وعمليات عرض المحتوى" لتسهيل فهمها على القارئ لأول مرة - إضافة تمثيل مرئي للبنية وكيفية ربط العمليات وطريقة تواصلها والاختلاف الأساسي بينها أمثلة على العناصر المرئية: واحد، اثنان، ثلاثة (جودة منخفضة). 2- توحيد المعلومات حول جميع الميزات التي يمكنك إضافتها إلى تطبيقك المستنِد إلى Electron ويشمل ذلك إعادة كتابة الأدلة لكي تتضمّن مجموعة موحَّدة من التعليمات حول كيفية تثبيت/تفعيل ميزة إلى جانب مثال على كيفية عمل الميزة. بالإضافة إلى ذلك، سيتم إنشاء صفحة جديدة (ملخّص) تعرض جميع الميزات المتاحة للاستخدام. قد تظهر التعليمات الموحّدة على النحو التالي: - نظرة عامة - مثال: - عيّنة تعليمات برمجية - مثال مرئي (حيثما أمكن)
- تبسيط صفحة توزيع التطبيق. ويشمل ذلك ما يلي: أ. دمج "تجميع التطبيقات" في دليل "توزيع التطبيقات" ب. تقسيم طرق التوزيع إلى تلقائية ويدوية ج. استخدام electron-forge كمثال على التوزيع التلقائي د. الحصول على معلومات عن asar من صفحة "تجميع التطبيقات" ووصف نسخ الملفات المصدر وإنشاء أرشيف asar كمثالين على التوزيع اليدوي #### الأسبوع 4 سيتم تخصيص هذا الأسبوع لإعادة هيكلة دليل التوثيق. ويشتمل هذا البرنامج على:
1 - تقسيم الأدلة الحالية إلى ثلاث فئات على الأقل: أ. البدء السريع ب. التعرّف على الأساسيات ج. الخطوات المتقدّمة
ستتضمّن فئة "البدء السريع" الأدلة الأساسية (التثبيت والضبط والتوزيع) لإنشاء سلسلة متسقة من الأدلة التي ستسمح للمبتدئين بالبدء السريع من الصفر. يجب أن يحتوي كل دليل على روابط تؤدي إلى الأدلة السابقة/التالية في السلسلة.
قد تبدو البنية على النحو التالي: 1. المتطلّبات الأساسية 2- ثبِّت Electron 3. إنشاء تطبيق أساسي 4- تجميع/توزيع التطبيق
بعد إكمال قسم "التشغيل السريع"، سيتعرّف المستخدم على أساسيات آلية عمل تطبيقات Electron وسيحصل على تطبيق Electron قابل للتوزيع ويعمل بشكل كامل.
ستتضمّن فئة "التعرّف على الأساسيات" الأدلة التي تهدف إلى تعزيز المعرفة حول Electron وتوسيع نطاق التطبيق الذي تم إنشاؤه في أقسام "البدء السريع". تتضمن هذه الأدلة ما يلي: - بنية التطبيق - إضافة ميزات إلى التطبيق - النصوص النموذجية ومعرّفات لوحة التحكّم في البيانات (CLI)
ستتضمّن فئة "الخطوات المتقدّمة" أدلة أكثر تقدمًا تهدف إلى ضبط تطبيق Electron وتحسينه: - الاختبار وتصحيح الأخطاء - تسهيل الاستخدام - الأمان - التحديثات
2 - تقليل عدد صفحات المستندات يحتوي الإصدار الحالي من المستندات على قدر معيّن من المحتوى المتداخل والتعليمات غير المصنّفة. على سبيل المثال: - تثبيت وتثبيت Electron ضمن "كتابة تطبيقك الأول" - إنشاء حزمة للتطبيق وتجميعه في ملف ضمن "توزيع التطبيق" - تعليمات غير مصنَّفة في الفئتَين "التفاصيل" و"المتقدّمة": اقتراح: نقل المستندات التالية إلى GitHub واستبعادها من المستندات الرئيسية. هذه المستندات مخصّصة لإرشادات تطوير Electron، ومستودع المصدر هو أول مكان للبحث عنها: - تطوير Electron - تطوير Chromium - تطوير V8 - المشاكل في Electron - الإصلاحات في Electron - طلبات سحب الرمز البرمجي - بنية دليل رمز المصدر - الاختبار - أسلوب الترميز
تتمثل الفكرة الرئيسية في هذا الإجراء في التخلص من عدد كبير جدًا من الأدلة المتاحة، ودمج أجزاء المعلومات المتناثرة معًا، ومنح الوافدين الجدد إصدارًا أكثر تنظيمًا وسهولة في التنقّل وسهولة الاستخدام من مستندات Electron.
الأسابيع 5 - 7
سيتم تخصيص الأسبوع الخامس لإعداد نموذج (طريقة) حول كيفية دمج electron-api-demos في المستندات الرئيسية. قد يبدو هذا النموذج على النحو التالي: 1. في المستندات الرئيسية، ضمن "إضافة ميزات إلى تطبيقك"، أنشئ الفئات المعروضة في electron-api-demos 2. من خلال الاطّلاع على كل فئة من الفئات، انقل أمثلة العرض التوضيحي إلى الوثائق الرئيسية: - يمكن أخذ عيّنات التعليمات البرمجية إما من رمز المصدر أو من وصف الميزة المقابلة في التطبيق. - يجب أن يتبع كل مثال من الأمثلة التي تم نقلها الوصف المرتبط به - يجب نقل كل مثال فرعي (على سبيل المثال، مربّع حوار الخطأ كعنصر فرعي لمربعات حوار "استخدام النظام") ضمن العنصر الرئيسي له.
ملاحظة 1: هناك أمثلة متوفّرة في كلّ من electron-api-demos وفي المستندات الرئيسية (على سبيل المثال، اختصارات لوحة المفاتيح والسحب والإفلات). في هذه الحالة، يجب أن يحظى المثال من electron-api-demos بالأولوية ويجب تجاهل المثال في المستندات الرئيسية.
ملاحظة 2: تتضمّن العديد من الأمثلة في تطبيق electron-api-demos معاينة تجريبية مباشرة للميزة أو الوظيفة الموضّحة. سيتم تجاهل هذه الوظيفة إلى أن يتم دمج Electron Fiddle في الأسابيع من 9 إلى 10.
- عدِّل الصفحة التي تسرد جميع الميزات المتاحة للاستخدام (التي تم إنشاؤها خلال الأسبوع 3) مع مراعاة التسلسل الهرمي الجديد للأمثلة.
سيتم تخصيص الأسبوعَين 6 و7 لنقل أمثلة electron-api-demos إلى المستندات الرئيسية وفقًا للقالب الموضّح أعلاه. في الخطوة الأخيرة، يجب حذف مستودع electron-api-demos أو إيقافه نهائيًا.
الأسابيع 8 - 10
سيتم تخصيص الأسبوع 8 لإعداد نموذج (طريقة) لكيفية دمج Electron Fiddle في الوثائق الرئيسية. وقد تم إطلاق هذه المبادرة بالفعل (تحقق من التفاصيل في المشكلة رقم 20442) من قبل شباب Electron مع متطوعين من المجتمع، ولكنها تتطلب وضع نهائي مناسب.
لمتابعة نماذج Fiddle، قد يظهر النموذج الأساسي على النحو التالي: 1. اختَر مثالاً من المستندات الرئيسية (مثل دليل البدء السريع). في هذه المرحلة، من المفترض أن تتضمّن المستندات أمثلة على electron-api-demos أيضًا. 2. أعِد إنشاء المثال في Electron Fiddle (باستخدام مثال الرمز البرمجي أو رمز المصدر كنقطة بداية). 3. احفظ Fiddle محليًا في مجلد؛ 4. انقل المثال إلى /docs/fiddles/[CATEGORY]/[SECTION]/[DEMO]. * يتم وصف قائمة الأمثلة المكتملة ضمن قسم "قائمة العروض التوضيحية" للمشكلة. 5- أضِف الزر "التشغيل في Fiddle" كما هو موضّح في التعليق الأوّلي في المشكلة رقم 2848.
سيتم تخصيص الأسبوعَين 9 و10 لدمج أمثلة electron-api-demos (التي سبق أن تم تحويلها إلى Fiddles) في المستندات الرئيسية وفقًا للنموذج الموضّح أعلاه.
الأسبوع 11
سيتم تخصيص هذا الأسبوع بشكل كامل لوضع اللمسات الأخيرة على مشروع الكتابة بعد النقل الناجح لمستودع إلكترون api-demos وعينات إلكترون Fiddle. ويشمل ذلك: - التحقّق من أنّ جميع أمثلة الرموز الحالية تحتوي على الزر "بدء التشغيل في Fiddle" والتأكّد من أنّ جميع أمثلة الرموز الحالية تعمل بشكل صحيح مثل Fiddles أو التأكّد من أنّ المستندات الرئيسية لم تعُد تشير إلى مستودع إلكترون API-demos
الأسبوع 12
الانتهاء من العمل المكتمل. عمليات التحقّق من القبول