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

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

ملخص المشروع

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

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

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

نيميشنb

اسم المشروع:

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

مدة المشروع:

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

وصف المشروع

ملخص المشروع

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

خطة المشروع

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

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

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

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

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

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

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

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

الحل

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

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

الإيجابيات:

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

السلبيات:

1. عدم وجود تحكم مطلق في النمط.

= استخدام Sphinx يمكننا في الأصل استخدام 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 فهذا يوفر حلاً بديلاً لـ markdown بدلاً من ذلك.

الإيجابيات:

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

السلبيات:

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

= استخدام MKdocs يمنحك ذلك حلاً بديلاً آخر لتحرير المستندات.

الإيجابيات:

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. لقد أعجبتُ بموقع واجهة المستخدم الدلالية (الذي يستخدم StoryBook) لأنه يتمتع بمظهر بسيط ويمكن للمرء بسهولة معرفة ما يريده بعد بضع نقرات فقط. وبصرف النظر عن واجهة المستخدم الدلالية، ألقيتُ أيضًا نظرة على Material Design، وPrimer، و Bootstrap، وCarbon Design، وغيرها لاستخدامها كأدلة لتصميم واجهة المستخدم وأنظمة تصميم لعملي. يمكننا أيضًا البحث عن مظاهر وثائق Jekyll الجاهزة لاستلهام الأفكار منها أيضًا.