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

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

ملخص المشروع

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

مؤسسة المشاع الإبداعي

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

nimishnb

اسم المشروع:

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

طول المشروع:

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

وصف المشروع

ملخص المشروع

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

خطة المشروع

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

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

3. المواصفات: يمكن تحديد المواصفات استنادًا إلى المتطلبات. يمكن تكوين المحتوى في الوثائق من خلال البيانات الموجودة في مواقع Netlify الإلكترونية، إلى جانب بعض الأفكار المُلهمة من الوثائق المعروفة جيدًا مثل واجهة المستخدم الدلالية، ومكتبة ساي كيت ليرن، ومكتبة نامبي، ومكتبة إبراهيم التمهيد وما إلى ذلك. وسيكون ناتج هذه المهمة هو الصفحة المقصودة المطلوبة وأدلّة التوثيق الكاملة.

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

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

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

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

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

الحل

هناك حلول متعددة ممكنة. ومع ذلك، سأتطرق إلى القليل هنا، وأقدم الحل النهائي في جزء الخاتمة:-

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

الإيجابيات:

1. طريقة مقبولة على نطاق واسع لإنشاء المستندات، وتستخدمها مؤسسات مثل Ethereum (Solidity).
2. توثيق بنية مثالية:
3. استضافة ثابتة مجانية

السلبيات:

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

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

الإيجابيات:

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

السلبيات:

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

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

الإيجابيات:

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

السلبيات:

1. قد لا توفر أفضل بنية للوثائق.

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

الإيجابيات:

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

السلبيات:

1. قد يستغرق هذا الأسلوب وقتًا أطول.

= استخدام Haroopad يقدم هذا حلاً بديلاً بدلاً من ذلك.

الإيجابيات:

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

السلبيات:

1. عدم القدرة على التحكم في CSS.
2. قد يحصل أو لا يحصل على أفضل دعم من المنتدى.
3. قد لا يكون متوافقًا مع MDX.

= استخدام MK Docs. يقدم هذا حلاً بديلاً آخر بدلاً من ذلك.

الإيجابيات:

1. ويشمل ذلك الحد الأدنى من الترميز (مجددًا).
2. اكتب المزيد باستخدام أسلوب Code Less.

السلبيات:

1. عدم القدرة على التحكم في CSS.
2. قد لا يحصل على أفضل دعم من المنتدى.
3. يستخدم لغة بايثون، وقد تكون هناك حاجة إلى لف مثيل Amazon S3.

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

الإيجابيات:

1. الالتزام بالتقنيات التي تضمن العمل على ما يرام، بالنظر إلى تجارب العمل السابقة.
2. الدراية بقاعدة الرموز
3. ما مِن تكنولوجيا فعّالة في هذا المجال.

السلبيات:

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

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