مشروع المشاع الإبداعي

تحتوي هذه الصفحة على تفاصيل مشروع كتابة فني مقبول في موسم Google من المستندات.

ملخص المشروع

مؤسسة مفتوحة المصدر:

Creative Commons

الكاتب الفني:

nimishnb

اسم المشروع:

دليل استخدام المفردات

طول المشروع:

المدة العادية (3 أشهر)

وصف المشروع

ملخّص المشروع

تتوفّر إمكانات هائلة لاستخدام Vocabulary كمكتبة أساسية لمكوّنات واجهة المستخدم لإنشاء المواقع الإلكترونية. ما تحتاجه هو دليل إرشادي فعّال وسهل الاستخدام. تشكّل معلومات المطوّرين المهمة، مثل أدلة المكوّنات ومواصفات الاستخدام وتعديلات الضبط، جزءًا أساسيًا من أي مستندات. سيشجّع ذلك المستخدمين الحاليين على التعرّف على كيفية تطوّر المفردات اللغوية والوصول إلى معالم جديدة، كما سيعزز استخدام المفردات في مشاريع حديثة نسبيًا. إنّ النتائج المطلوبة من فترة تدريبي لن تشمل فقط كتابة دليل عملي لاستخدام المكوّنات الحالية، بل تشمل أيضًا تصميم وتطوير صفحة رئيسية (تؤدي إلى توثيق متكامل لكل منها) لكل من Vocabulary وVue-Vocabulary وFonts.

خطة المشروع

1. المشكلة: المستندات هي أحد الأسباب الأساسية التي تحدّد مدى نجاح مكتبة مفتوحة المصدر معيّنة. إنّ السؤال الرئيسي الذي يطرحه المطوّرون عند اختيار حزمة تقنية مناسبة لإنشاء تطبيقاتهم هو "هل المكتبة موثّقة بشكل جيد؟ هل تتم صيانته بشكل جيد؟ هل تتوفّر فيه مساعدة كبيرة بشأن الاستخدام والأخطاء؟ هذه هي الأسئلة التي يجب أن نطرحها على أنفسنا أثناء تنفيذ فكرة المشروع هذه. من منظور هندسة البرمجيات:

2. تحليل المتطلبات: هناك حاجة ملحّة إلى الحصول على مستندات موجزة ومجمّعة لتلبية احتياجاتنا. يؤثّر عدم توفّر المستندات سلبًا في آفاق التطبيقات المفتوحة المصدر المستقبلية، وهو عنصر أساسي ومهمّ إلى حدٍ كبير. يجب أن يكون الربط بهذه الوثائق صفحة رئيسية جذابة تجذب اهتمام الأشخاص على الفور. يجب أن تكون المستندات منظمة بشكل جيد، ما يتيح التنقّل فيها بسلاسة.

3. المواصفات: يمكن تحديد المواصفات استنادًا إلى المتطلبات. يمكن إنشاء المحتوى في المستندات من البيانات المتوفّرة في مواقع CC netlify الإلكترونية، بالإضافة إلى بعض الأفكار المستوحاة من المستندات المعروفة، مثل semantic-ui وscikit-learn وnumpy وbootstrap وما إلى ذلك. وستكون نتيجة هذه المهمة هي الصفحة المقصودة المطلوبة وأدلة المستندات الكاملة.

في ما يلي بعض المشاكل العامة المرتبطة بـ Vocabulary وVue-Vocabulary وFonts حاليًا:

• لا تتوفّر مستندات، وحتى إذا كانت متوفّرة، تكون أجزاء منها متناثرة في جميع أنحاء مواقع netlify الإلكترونية. ولا يؤدي ذلك إلى منع المستخدمين أو المطوّرين أو المساهمين الخارجيين من استخدام مكتبتنا.

  • يتطلب الوصول إلى مكون معين ونسخ الرمز المقابل له نقرات إضافية. لا يؤدي إجراء بحث بسيط على Google عن عبارة مثل "مكوّن Tabs CC Vocabulary" إلى عرض المعلومات المطلوبة. سيؤدي خيار البحث ضمن أدلة المستندات إلى تحسين تجربة المستخدم بشكل كبير.

  • وصف نصي أكثر تفصيلاً للمكونات، يصف التفاصيل غير الواضحة.

  • لا يتوفّر خيار التشغيل المباشر. تتيح مواقع إلكترونية مختلفة، مثل JSFiddle، إجراء عمليات تشغيل مباشرة، ما يتيح للمطوّرين التعرّف على المكوّن بدون تشغيل تطبيق كامل لمعرفة كيفية عمله.

الحلّ

هناك عدة حلول ممكنة. ومع ذلك، سأتناول بعضًا منها هنا، وسأقدّم الحل النهائي في الجزء الختامي:-

= استخدام readthedocs readthedocs هو حلّ معروف لكتابة مستندات المكتبات المفتوحة المصدر. ويستند إلى Sphinx، وهي أداة مستندات Python.

الإيجابيات:

1. شكل مقبول على نطاق واسع لإنشاء المستندات، وتستخدمه مؤسسات مثل Ethereum ‏ (Solidity).
2. مستندات منظَّمة على النحو الأمثل
3. استضافة ثابتة مجانية

السلبيات:

1. عدم التمكّن من التحكّم المطلق في التصميم

= استخدام Sphinx يمكننا استخدام Sphinx بشكل أساسي في جزء التوثيق أيضًا، فهو يقدّم ميزات جيدة لجميع أغراضنا.

الإيجابيات:

1. أداة بايثون الأكثر شيوعًا لإنشاء المستندات
2. يدعم البحث عن المستندات أيضًا.
3. يمكن إلغاء ملف CSS التلقائي باستخدام ملف مخصّص، وبعض عناصر التحكّم في HTML باستخدام ملفات ‎.rst

السلبيات:

1. سيتضمّن ذلك الترميز بلغة Python وتنسيق نص مُعاد تنظيمه (‎.rst)، ما سيشكّل انحرافًا عن لغات المشروع المقترَحة.

= استخدام مظاهر Jekyll يتم دمج مظاهر Jekyll ضمن صفحات GitHub، وهناك نماذج حالية يمكن تخصيصها حسب احتياجاتنا.

الإيجابيات:

1. مواضيع توثيق جاهزة لجميع الأغراض.
2. يمكن أن يتم إلغاء CSS والأنماط التلقائية باستخدام أنماط مخصّصة، ما يتيح لك التحكّم في HTML أيضًا.
3. يتم سحب ملف CSS التلقائي في Primer لإنشاء الصفحات.
4. تكامل سهل مع صفحات GitHub.

السلبيات:

1. قد لا يوفّر أفضل بنية للمستندات.

=استخدام صفحات GitHub صفحات GitHub العادية لإنشاء موقعنا الإلكتروني الثابت (HTML وCSS وJS).

الإيجابيات:

1. التحكم الكامل في كل شيء تقريبًا.
2. أقصى قدر من المرونة في اختيار التنسيق والألوان والأنماط
3. سهولة استخدام مكوّنات "المفردات"
4. تضمين مقتطفات الرموز البرمجية وروابط التشغيل المباشر بسهولة

السلبيات:

1. قد يكون هذا الإجراء أكثر استهلاكًا للوقت.

= استخدام Haroopad يقدّم هذا الإجراء حلًا بديلاً لتنسيق Markdown.

الإيجابيات:

1. أن تتطلّب الحد الأدنى من الرموز البرمجية المعقدة
2. يكون التركيز على كتابة الوثائق بشكل مثالي.

السلبيات:

1. عدم التحكّم في خدمة مقارنة الأسعار (CSS)
2. قد تتوفر فيه أفضل ميزات الدعم من المنتدى أو لا.
3. قد لا يكون متوافقًا مع MDX.

= استخدام MKDocs يقدّم هذا البديل الآخر لتنسيق Markdown.

الإيجابيات:

1. سيتطلّب ذلك الحد الأدنى من الرموز البرمجية المعقدة (مرة أخرى).
2. اكتب المزيد باستخدام منهج Code Less.

السلبيات:

1. عدم التحكّم في خدمة مقارنة الأسعار (CSS)
2. قد لا تتوفر لديك أفضل مساعدة من المنتدى.
3. يستخدم هذا الإجراء لغة Python، وقد تحتاج إلى إنشاء نسخة من Amazon S3.

= استخدام VueJS +StorybookJS يشيع استخدام هذا النهج عبر المفردات والمستودعات التابعة لها.

الإيجابيات:

1. الاعتماد على التقنيات التي يُضمن نجاحها استنادًا إلى تجارب العمل السابقة
2. الإلمام بقاعدة الرموز
3. ما مِن تكنولوجيا مختصة في هذا المجال.

السلبيات:

1. وقد تتوفّر أيضًا خيارات أبسط للأغراض نفسها.

في الختام، أعتقد أنّ الطريقة التي تتضمّن VueJS+Storybook (HTML وCSS وJS) هي الأنسب، لأنّني أشعر بالراحة عند استخدامها أيضًا. ومع ذلك، يعني ذلك أيضًا أنّنا لن نبذل قصارى جهدنا في تطوير هذا التطبيق. سيكون من السهل أيضًا استخدام مكونات CC-Vocabulary. ومع ذلك، لتحديد هيكل الوثائق، يجب أن نفكر بالتأكيد في طريقة تقسيم المحتوى بين العناوين الفرعية في وثائق readthedocs. لقد أعجبني موقع Semantic-UI الإلكتروني (الذي يستخدم StoryBook) لأنّه يتميز بمظهر بسيط ويمكن للمستخدم التعرّف بسهولة على ما يريده بعد بضع نقرات فقط. بالإضافة إلى Semantic-UI، اطّلعت أيضًا على Material Design وPrimer وBootstrap وCarbon Design وغيرها لاستخدامها كأدلة تنسيق واجهة المستخدم وأنظمة التصميم في عملي. يمكننا أيضًا البحث عن مواضيع جاهزة لمستندات Jekyll للحصول على الإلهام لنفس الموضوع.