تحتوي هذه الصفحة على تفاصيل مشروع كتابة تقنيّة تم قبوله في موسم المستندات من Google.
ملخص المشروع
- المؤسسة المفتوحة المصدر:
- إلكترون
- الكاتب التقني:
- السيدة الذهبية
- اسم المشروع:
- مسار برنامج Electron التعليمي
- مدة المشروع:
- المدة العادية (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. تضمين مستودع Electronic-api-demos في الوثائق. يحتوي مستودع Electronic-api-demos على مجموعة من الأمثلة التي توضح كيفية إضافة ميزات إلى تطبيق Electron الخاص بك. يجب تضمين هذه المعلومات في دليل "إضافة ميزات إلى تطبيقك" بما يتوافق مع استراتيجية واحدة لمحتوى الحقيقة. 5. ادمج أمثلة Electron Fiddle في الوثائق. ستسهّل هذه الخطوة على المطوّرين الجدد معرفة كيفية عمل جزء معيّن من الرمز بدون الحاجة إلى تكرار الخطوات يدويًا. يتضمن التكامل كتابة عيّنات تعليمات برمجية للأدلة التوجيهية المحدّثة وإضافة زر "Launch in Fiddle" (تشغيل في Fiddle) إلى مجموعات التعليمات البرمجية.
مجريات المباراة
فترة مراجعة الطلب: تعرف على المنتدى والأشخاص الذين تريد العمل معهم. اطّلِع على أدلة مساهمات المنتدى وأفضل الممارسات. قدِّم المساهمات الأولى. الترابط بين أفراد المنتدى - استكشاف المنتدى افحص الحالة الحالية لوثائق Electron. تحديد نقاط الضعف. الأسبوع 1 - التوافق مع الموجهين بشأن المراحل الرئيسية للمشروع والمُخرَجات النهائية الأسبوع 2: مراجعة بيئة مطوّري البرامج وكتابة صفحات تطبيقك الأول على Electron الأسبوع 3: مراجعة بنية التطبيق وإضافة ميزات إلى تطبيقك وصفحات حزمة التطبيق والتوزيع. إنشاء صفحة ملخص مع قائمة بالميزات التي يمكن إضافتها إلى التطبيق الأسبوع 4 - إعادة هيكلة دليل الوثائق الأسبوع 5 - إعداد نموذج لكيفية دمج Electronic-api-demos في الوثائق الرئيسية الأسابيع 6 - 7 - نقل مستودع Electronic-api-demos الأسبوع 8 - إعداد نموذج للوثائق الرئيسية التي سيتم دمج Electron فيها اكتب العيّنة الأولى. الأسابيع 9 - 10 - دمج Electron Fiddle في المستندات الرئيسية الأسبوع 11 - الانتهاء من بنية الوثائق الرئيسية والصفحات بعد نقل مستودع Electronic-api-demos وعينات Electron Fiddle الأسبوع 12 - تقييم النتائج
تحليل تفصيلي للإنجازات
فترة مراجعة الطلب سيتم تخصيص الجزء الأول من الفترة للتحقّق من قنوات المنتدى والرمز المصدر والتواصل مع الأشخاص المخصّصين للمشروع.
في الجزء الثاني من الفترة، سيتم تخصيص الجزء الثاني من تلك الفترة للتحقق من ثقافة المساهمات بشكل عام، وفحص أدلة المساهمات وأفضل الممارسات. وسيكون هذا هو الوقت المناسب للمساهمات الأولى لمعرفة كيف يتم ذلك.
توطيد العلاقات مع أفراد المنتدى
سيتم تخصيص هذه المرة لفحص أعمق لمجلد الوثائق إلى جانب خارطة الطريق الخاصة به. بناءً على هذه المعلومات، سيكون من الممكن تحديد نقاط الضعف (على سبيل المثال، الأجزاء غير المكتملة أو المفقودة) التي يمكن تحسينها. أنشئ طلبات سحب (حيثما أمكن) لملء هذه الفجوات.
الأسبوع 1 - الأسبوع 2
سيتم تخصيص الأسبوع الأول للتواصل مع المرشدين من أجل التوافق مع المعالم الرئيسية المتوقعة وتسليمهم في الوقت المناسب.
وفي الأسبوع الثاني، سنتناول مراجعة بيئة مطوّر البرامج وكتابة صفحات تطبيقك الأول على Electron. بالنسبة إلى صفحة بيئة المطوِّرين، ستتضمن إعادة كتابة نظرة عامة والتدقيق اللغوي. بالنسبة إلى صفحة كتابة تطبيق Electron الخاص بك، سيتضمن ذلك جعل الصفحة دليلاً تفصيليًا متسقًا يحتوي على نقطتَي بداية ونهاية واضحتين، وإزالة المعلومات المتكررة (مثل كتلتين من الرموز المتشابهة ضمن قسم Electron Development في Nutshell و"تجربة هذا المثال" ).
المُخرَجات النهائية: أدلة مقدمة منقحة وسهلة المتابعة حول كيفية البدء السريع في استخدام تطبيقات Electron
الأسبوع 3
سيتم تخصيص هذا الأسبوع للأهداف التالية: 1. تحسينات على صفحة "بنية التطبيقات". ويشمل ذلك ما يلي: - إعادة كتابة المعلومات الحالية في القسم "عمليات الرئيسي" و"عمليات العارض" بهدف تبسيط وتسهيل فهم القارئ لأول مرة - إضافة تمثيل مرئي للبنية، وكيفية ارتباط العمليات، وكيفية تواصلها، واختلافها الأساسي أمثلة على العناصر المرئية: واحد، اثنان، ثلاثة (جودة منخفضة). 2. توحيد المعلومات حول جميع الميزات التي يمكنك إضافتها إلى تطبيق Electron الخاص بك. وهذا يشمل إعادة كتابة الأدلة بحيث يكون لديهم مجموعة موحدة من التعليمات حول كيفية تثبيت/تمكين ميزة إلى جانب مثال على كيفية عمل الميزة. بالإضافة إلى ذلك، سيتم إنشاء صفحة جديدة (ملخّص) تسرد جميع الميزات المتاحة للاستخدام. وقد تظهر التعليمات الموحّدة على النحو التالي: - نظرة عامة - مثال: - نموذج الرمز - مثال مرئي (حيثما أمكن)
- تبسيط صفحة "توزيع التطبيق". يتضمن ذلك ما يلي: أ. دمج حزمة التطبيق في دليل توزيع التطبيقات ب- تقسيم طرق التوزيع إلى طريقة تلقائية ويدوية ج- استخدام الإلكترونات كمثال للتوزيع التلقائي د. الحصول على معلومات عن حِزم التطبيق من صفحة "تغليف التطبيقات" ووصف نسخ الملفات المصدر وإنشاء أرشيف asar كأمثلة للتوزيع اليدوي. #### الأسبوع 4 سيتم تخصيص هذا الأسبوع لإعادة هيكلة دليل التوثيق. ويشمل ذلك:
1 - تقسيم الأدلة الحالية إلى ثلاث فئات على الأقل: أ. التشغيل السريع ب: تعلُّم الأساسيات ج. الخطوات المتقدّمة
ستحتوي فئة البدء السريع على البرامج التعليمية الأساسية (التثبيت والضبط والتوزيع) لإنشاء سلسلة متسقة من الأدلة التي ستتيح للمبتدئين البدء السريع من نقطة الصفر. يجب أن يحتوي كل دليل على روابط إلى الأدلة السابقة/التالية في السلسلة.
قد يبدو البنية على النحو التالي: 1- المتطلبات الأساسية 2. ثبِّت Electron 3- إنشاء تطبيق أساسي 4- حزمة/توزيع التطبيق
بعد الانتهاء من قسم البدء السريع، سيعرف المستخدم أساسيات كيفية عمل تطبيقات Electron وسيكون لديه تطبيق Electron قابل للتوزيع يعمل بالكامل.
ستحتوي فئة تعلم الأساسيات على الأدلة التي تهدف إلى تقوية المعرفة حول Electron وتوسيع نطاق التطبيق الذي تم إنشاؤه في أقسام Quickstart. تتضمن هذه الأدلة ما يلي: - بنية التطبيق - إضافة ميزات إلى تطبيقك - النصوص النموذجية وCLI
ستحتوي فئة الخطوات المتقدمة على أدلة أكثر تقدّمًا تهدف إلى ضبط تطبيق Electron وضبطه: - الاختبار وتصحيح الأخطاء - تسهيل الاستخدام - الأمان - التحديثات
2 - تقليل عدد صفحات التوثيق. تحتوي النسخة الحالية من الوثائق على درجة معينة من المحتوى المتداخل والتعليمات بلا فئة. على سبيل المثال: - التثبيت وتثبيت Electron في قسم "كتابة تطبيقك الأول" - إنشاء حزمة من التطبيق وتجميعه في ملف ضمن "توزيع التطبيق" - تعليمات بلا فئة في الفئتَين "تفاصيل" و"متقدم": اقتراح: نقل المستندات التالية إلى GitHub واستبعادها من المستندات الرئيسية. هذه المستندات خاصة بإرشادات تطوير Electron ومستودع المصدر هو أول مكان نبحث عنها: - تطوير Electron - تطوير Chromium - تطوير V8 - مشاكل في Electron - رموز التصحيح في Electron - طلبات السحب - بنية دليل رموز المصادر - الاختبار - نمط الترميز
والهدف الرئيسي من التقليل هو التخلص من مجموعة كبيرة من الأدلة المتاحة، والجمع بين المعلومات المبعثرة والمليئة بالألغاز وتقديم نسخة من مستندات Electron منظّمة وسهل التنقل وسهل الاستخدام للمستخدمين الجدد.
الأسابيع 5 إلى 7
سيتم تخصيص الأسبوع 5 لإعداد قالب (طريقة) لكيفية دمج Electronic-api-demos في الوثائق الرئيسية. قد يبدو هذا القالب كما يلي: 1. في الوثائق الرئيسية، ضمن "إضافة ميزات إلى تطبيقك"، يمكنك إنشاء الفئات الممثلة في Electronic-api-demos 2. من خلال الاطّلاع على كل فئة من الفئات، انقل الأمثلة التجريبية إلى الوثائق الرئيسية: - يمكن أخذ عيّنات التعليمات البرمجية من الكود المصدر أو من وصف الميزة المقابلة في التطبيق - يجب أن يتبع كل مثال منقول الوصف المرتبط - يجب نقل كل مثال فرعي (على سبيل المثال، مربع حوار خطأ كعنصر فرعي لمربعات حوار "استخدام النظام") ضمن العنصر الرئيسي
الملاحظة رقم 1: هناك أمثلة متوفرة في الإصدارات التجريبية لواجهة برمجة التطبيقات الإلكترونية وفي المستندات الرئيسية (على سبيل المثال، اختصارات لوحة المفاتيح والسحب والإفلات). في هذه الحالة، يجب أن يأخذ المثال من Electronic-api-demos الأولوية، ويجب تجاهل المثال الوارد في الوثائق الرئيسية.
ملاحظة رقم 2: تتضمن العديد من الأمثلة في تطبيق Electronic-api-demos معاينة للعرض التوضيحي المباشر للميزة أو الوظيفة الموصوفة. وسيتم تجاهل هذه الوظيفة إلى أن يتم دمج إلكترون كمال في الأسابيع من 9 إلى 10.
- قم بتحديث الصفحة التي تسرد جميع الميزات المتاحة للاستخدام (التي تم إنشاؤها خلال الأسبوع 3) مع مراعاة التسلسل الهرمي الجديد للأمثلة.
سيتم تخصيص الأسبوعين 6 و7 لنقل أمثلة Electronic-api-Demos إلى الوثائق الرئيسية وفقًا للقالب الموضح أعلاه. كخطوة أخيرة، يجب حذف مستودع Electronic-api-demos أو إيقافه.
الأسابيع 8 - 10
سيكون الأسبوع 8 مخصصًا لإعداد قالب (طريقة) لكيفية دمج Electron Fiddle في الوثائق الرئيسية. سبق وأن أطلق أعضاء Electron هذه المبادرة (راجع التفاصيل في المشكلة رقم 20442) بالتعاون مع متطوعين من المجتمع، ولكنها تتطلب إنهاءًا سليمًا لهذه المبادرة.
لمتابعة نماذج Fiddle، قد يبدو النموذج الأساسي كما يلي: 1- اختر مثالاً من الوثائق الرئيسية (على سبيل المثال، التشغيل السريع). في هذه المرحلة، يجب أن تحتوي الوثائق أيضًا على أمثلة توضيحية لواجهة برمجة التطبيقات الإلكترونية 2. أعِد إنشاء المثال في Electron Fiddle (إما باستخدام نموذج الرمز أو رمز المصدر كنقطة بداية). 3. احفظ Fiddle محليًا في مجلد؛ 4. انقل المثال إلى /docs/fiddles/[CATEGORY]/[SECTION]/[DEMO]. * يتم وصف قائمة الأمثلة المكتملة ضمن قسم "قائمة العروض التوضيحية" للمشكلة. 5. أضِف زر "التشغيل في كمال" كما هو موضح في التعليق الأولي في المشكلة رقم 2848.
سيتم تخصيص الأسبوعين 9 و10 لدمج أمثلة Electronic-api-demos (التي تم تحويلها بالفعل إلى Fiddles) إلى الوثائق الرئيسية وفقًا للقالب الموضح أعلاه.
الأسبوع 11
سيتم تخصيص هذا الأسبوع بالكامل لإنهاء مشروع الكتابة بعد النقل الناجح لمستودع Electronic-api-demos وعينات Electron Fiddle. ويشمل ذلك ما يلي: - التأكّد من أنّ جميع أمثلة الرموز الحالية تتضمّن الزر Launch in Fiddle والتحقّق من أنّ جميع أمثلة الرموز الحالية تعمل بشكل صحيح مثل Fiddles التأكّد من أنّ المستندات الرئيسية لم تعُد تشير إلى مستودع Electronic-api-demos
الأسبوع 12
الانتهاء من العمل المكتمل. عمليات التحقّق من القبول